# `cso_colocate` module

The `cso_colocate` module provides classes to collect observations and simulations from pixels that are co-located with surface locations.

## Class hierchy

The classes and are defined according to the following hierchy:

- `UtopyaRc`

  - `CSO_CoLocate`

  - `CSO_CoLocatePlotTimeSeries`

## Classes

class cso_colocate.CSO_CoLocate(rcfile, rcbase='', env={}, indent='')

  Bases: `UtopyaRc`

  Collect time series of observations and/or simulations co-located with surface locations. The value assigned to location and time is an average over all pixels within a specified distance and valid for the time.

  Location should be specified in a csv file with columns at least longitude and latiude:

      name                   ;longitude;latitude
      Peyrusse Vieille       ;     0.18;   43.62
      San Pablo de los Montes;    -4.35;   39.55
      Lahemaa                ;    25.9 ;   59.5

  The column names are not pre-defined, and additional columns are allowed too. Lines that start with `'#'` are ignored. By default the seperation character is `';'`, with surrounding white-space ignored. In the settings, specifiy the name of the csv file and eventually other characters for the seperation and comment:

      ! table with station locations:
      <rcbase>.locations.file           :  /data/stations.csv
      ! special characters:
      <rcbase>.locations.sep            :  ;
      <rcbase>.locations.comment        :  #

  Also specify the column names that used for the longitude and latitude:

      ! column names:
      <rcbase>.locations.longitude      :  longitude
      <rcbase>.locations.latiutde       :  latiutde

  Time series are created within a time range:

      ! time range:
      <rcbase>.timerange.start        :  2018-06-01 00:00
      <rcbase>.timerange.end          :  2018-06-03 23:59

  Output is collected in files per time interval (daily, hourly). Specify the output freqency and a template for the name of the target file:

      ! time step: monthly, daily, ..
      <rcbase>.output.freq            :  monthly

      ! target file:
      <rcbase>.output.file            :   /scratch/colocated/timeseries_%Y%m.nc

  Specify a target time resolution; pixels are collected in intervals `[t1,t2)`

      ! time resolution: hourly
      <rcbase>.resolution             :  hourly

  Pixels are selected within a distance of a location:

      ! collect pixels within radion of km:
      <rcbase>.distance               :  100.0

  Input data could originate from different sources, for example a data file with footprints and retrieval, and a state file with simulations by a model. Specify a list with keywords describing the sources; the first source should be a file that contains the footprints:

      ! keywords for source files:
      <rcbase>.sources                :  data

  For each source, specify the input file(s) as a filename pattern:

      ! input file or filename pattern for each source type:
      <rcbase>.source.data         :  /scratch/output/CSO_output_%Y%m%d_%H%M_S5p-no2_data.nc

  The input could be filtered by applying selections, for example on quality value; see `CSO_File.SelectPixels()` method for supported filter types:

      ! keywords for filters:
      <rcbase>.filters                :  quality

      ! minimum quality value required:
      <rcbase>.filter.quality.var       :  qa_value
      <rcbase>.filter.quality.type      :  min
      <rcbase>.filter.quality.min       :  0.8
      <rcbase>.filter.quality.units     :  1

  Specify a list of the variables to be created, and for each of them the source type and source variable:

      ! data variables to be created:
      <rcbase>.output.vars            :  xvmr

      ! input variables:
      !   data:vcd    : from data file
      !   state:hx    : from state file
      <rcbase>.output.xvmr.source     :  data:xvmr

  Existing files are replaced if the following flag is set:

      ! renew existing files?
      <rcbase>.renew                  :  True

  To reduce file size, by default all variables are written to file as short-integers (2 bytes) accompanied by `add_offset` and `scale_factor` attributes. A flag is available to disable packing. In addition, `zlib` compression is enabled. The default compression level is 1 (out of 9); set the following flag to a higher level to have stronger compression (on expense of computation time), or set to 0 to disable compression:

      ! pack floats as shorts:
      <rcbase>.output.packed              :  True
      ! zlib compression level (default 1, 0 for no compression):
      <rcbase>.output.complevel           :  1

class cso_colocate.CSO_CoLocatePlotTimeSeries(rcfile, rcbase='', env={}, indent='')

  Bases: `CSO_CatalogueBase`

  Plot timeseries of averages over co-located pixels, as collected by the `CSO_CoLocate` class.

  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:

  In the settings, specify the range of the time series:

      ! time range:
      <rcbase>.timerange.start        :  ${my.timerange.start}
      <rcbase>.timerange.end          :  ${my.timerange.end}

  Input files are created by the `CSO_CoLocate` class; specify a file name pattern for the file(s):

      ! filter for input files:
      <rcbase>.input.files            :  /scratch/colocated/timeseries_*_daily.nc

  For each location a single figure will be created, with time series at one or more resolutions (daily, monthly), and one or more variables (observations, simulations). The filename should include a pattern to substitute at least one location property, for example a station code; if no suitable properties are available, the location index (1-based) could be used:

      ! target figure;
      ! see 'str.format' for substitution of station codes etc,
      ! use 'location' for 1-based index:
      !    timeseries_{code}.png
      !    timeseries_{location:0>3}.png
      <rcbase>.fig.file            :  /scratch/colocated/figs/timeseries_{location:0>3}.png

  By default existing files are created again:

      ! renew existing files?
      <rcbase>.renew                  :  True

  Define the figure size with:

      ! figure size:
      <rcbase>.fig.size            :  (8,4)

  The title could include substitutions for location properties:

      ! title, include location tempates:
      <rcbase>.fig.title           :  {name} ({longitude:7.2f},{latitude:6.2f})

  Also define the label for the y-axis, as well as the value range:

      ! label, use '{units}' template
      <rcbase>.fig.ylabel          :  Glyoxal tropospheric column [{units}]
      <rcbase>.fig.ylim            :  [None,None]

  The plot could include multiple temporal resolutions. The :py:meth:`xarray.DataArray.resample` method is used to create for example monthly average from daily time series. Specify a list of resolutions to be resampled, or use `N` for the native resolution:

      ! time resamplings:
      !   D=daily, M=monthly
      !   or "N" for native
      <rcbase>.resolutions         :  N M

  Specify a list of keywords for the variables to be plotted; for each variable, specify target units and line style (including label for legend) per temporal resolution:

      ! variables to be plotted:
      <rcbase>.vars                :  obs sim
      ! style for observations:
      <rcbase>.var.obs.units        :  umol/m2
      <rcbase>.var.obs.N.style      :  color='0.7', marker='.', linestyle='None'
      <rcbase>.var.obs.M.style      :  color='black', marker='o', linestyle='-', label='observations'
      ! style:
      <rcbase>.var.sim.units        :  umol/m2
      <rcbase>.var.sim.N.style      :  color='orange', alpha=0.5, marker='.', linestyle='None'
      <rcbase>.var.sim.M.style      :  color='orange', marker='o', linestyle='-', label='simulations'