
.. Label between '.. _' and ':' ; use :ref:`text <label>` for reference
.. _colocate:

***********
Co-locating
***********

The CSO package contains a tool to collect pixels that are
*co-located* with (for example) observaton sites.


Collect co-located pixels
=========================

The CSO post processing tools could be used to create grid averages.

The configuration of a co-location job looks like::

    ! single step:
    cso.gridded.class        :  utopya.UtopyaJobStep
    ! co-location collection task:
    cso.gridded.task.class   :  cso.CSO_CoLocate
    cso.gridded.task.args    :  '${PWD}/rc/settings.rc', \
                                          rcbase='cso.colocate'

The actual work is done by the :py:class:`.CSO_CoLocate` class,
see its description for details on the configuration.

The input for co-location is:

* a csv table with location information (names, longitudes, and latitudes)
* CSO files with pixel data

The result is a set of files with time series of averages over pixels
within a distance of the selected locations::

  timeseries_202001_daily.nc
  timeseries_202002_daily.nc
                  :


Plot timeseries over co-located pixels
======================================

The :py:class:`.CSO_CoLocatePlotTimeSeries` class could be used
to create plots of time series from the output of the 
:py:class:`.CSO_CoLocate` class.

The configuration of a co-location job looks like::

    ! single step:
    cso.gridded.class        :  utopya.UtopyaJobStep
    ! catalogue creation task:
    cso.gridded.task.class   :  cso.CSO_CoLocatePlotTimeSeries
    cso.gridded.task.args    :  '${PWD}/rc/settings.rc', \
                                          rcbase='cso.colocate-plot'

The following is an example of a timeseries plot that shows averages
over co-located pixels with 100 km of a site for at daily and hourly resolution:

.. figure:: figs/HCHO/timeseries_001.png
   :scale: 70 %
   :align: center
   :alt: Timeseries of averages over pixels collected within 100 km of site.
