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:

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:

Timeseries of averages over pixels collected within 100 km of site.

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'