# `cso_catalogue` module

The `cso_catalogue` module provides classes to create plots of CSO data.

## Class hierchy

The classes and are defined according to the following hierchy:

- `UtopyaRc`

  - `CSO_CatalogueBase`

    - `CSO_Catalogue`

    - `CSO_SimCatalogue`

    - `CSO_GriddedCatalogue`

## Classes

class cso_catalogue.CSO_CatalogueBase(rcfile=None, rcbase='', env={}, urc=None)

  Bases: `UtopyaRc`

  Base class for catalogues.

class cso_catalogue.CSO_Catalogue(rcfile, rcbase='', env={}, indent='')

  Bases: `CSO_CatalogueBase`

  CSO task to create catalogue of satellite data figures.

  The catalogue is created in an output directory specified with:

      <rcbase>.output.dir     :  /Scratch/CSO/catalogue

  A time range for which images should be created is specified with:

      ! specifiy timerange:
      <rcbase>.timerange.start  :  2012-01-01 00:00
      <rcbase>.timerange.end    :  2012-12-31 23:59

  The time range is used to select oribts from a listing file created during conversion from raw data:

      <rcbase>.input.listing        :  /Scratch/CSO/S5p/RPRO/NO2/Europe/listing.csv

  Specify a list of variables to be plotted:

      <rcbase>.vars                   :  vcd qa_flag

  Each `var` should be a variable in the orbit file, unless a different variable name is specified with:

      <rcbase>.var.vcd.source             :  vcd_trop

  Optionally specify target units that are different from the input:

      ! convert units:
      <rcbase>.var.vcd.units             :  1e15 mlc/cm2

  The value range of the colorbar could be tunes using (default limits are based on data values):

      <rcbase>.var.vcd.vmin              :   0.0
      <rcbase>.var.vcd.vmax              :  10.0

  The colors in the colorbar could be changed using:

      <rcbase>.var.qa_flag.colors        :   ['red','yellow','green']

  The label below the colorbar will by default show the variable name, unless a `long_name` is defined:

      <rcbase>.var.vcd.long_name         :   retrieved vertical column density

  The created images will have filenames including subdirectories for year/month/day:

      2018/06/01/S5p_RPRO_NO2_03278__vcd.png
                 S5p_RPRO_NO2_03278__qa_value.png

  Enable the following flag to re-create existing files, by default only non-existing files are created:

      <rcbase>.renew                  :  False

  The figures size could be specified to fine tune the shape:

      ! figure size (inches), default is (8,6):
      <rcbase>.figsize             :  (6,6)

  Specify the domain of the map, projection is regular longitude/latitude:

  > ! map domain (west east south north): <rcbase>.domain : -30 45 35 75

class cso_catalogue.CSO_SimCatalogue(rcfile, rcbase='', env={}, indent='')

  Bases: `CSO_CatalogueBase`

  CSO task to create catalogue of satellite observations and simulations.

  The catalogue is created in an output directory specified with:

      <rcbase>.output.dir     :  /Scratch/CSO/catalogue

  A time range for which images should be created is specified with:

      ! specifiy timerange:
      <rcbase>.timerange.start  :  2012-01-01 00:00
      <rcbase>.timerange.end    :  2012-12-31 23:59
      ! step is one of: hour | day | month
      <rcbase>.timerange.step   :  hour

  The time range is used to scan for output files from the satellite observation operator. Both a data file with for example footprints and observations, as well as a state file with simulations is needed:

      <rcbase>.input.data.file        :  /Scratch/model/output/CSO_output_%Y%m%d_%H%M_data.nc
      <rcbase>.input.state.file       :  /Scratch/model/output/CSO_output_%Y%m%d_%H%M_state.nc

  Specify a list of variables to be plotted, for example the retrieved and simulated column:

      <rcbase>.vars                   :  yr ys

  By default the `var` is expected to be a variable in the data file; use the following source specifications to explicitly define the origin:

      <rcbase>.var.yr.source                 ::  data:vcd
      <rcbase>.var.ys.source                 ::  state:vcd

  Optionally specify target units that are different from the input:

      ! convert units:
      <rcbase>.var.vcd.units             :  1e15 mlc/cm2

  The value range of the colorbar could be tunes using (default limits are based on data values):

      <rcbase>.var.vcd.vmin              :   0.0
      <rcbase>.var.vcd.vmax              :  10.0

  The colors in the colorbar could be changed using:

      <rcbase>.var.qa_flag.colors        :   ['red','yellow','green']

  The label below the colorbar will by default show the variable name, unless a `long_name` is defined:

      <rcbase>.var.vcd.long_name         :   retrieved vertical column density

  The name of the created image files is read from:

      ! target files, time tempates are replaced:
      <rcbase>.output.file            :  %Y/%m/%d/S5p_RPRO_NO2_%Y%m%d_%H%M_%{var}.png

      2018/06/01/S5p_RPRO_NO2_03278__vcd.png
                 S5p_RPRO_NO2_03278__qa_value.png

  Enable the following flag to re-create existing files, by default only non-existing files are created:

      <rcbase>.renew                  :  False

  The figures size could be specified to fine tune the shape:

      ! figure size (inches), default is (8,6):
      <rcbase>.figsize             :  (6,6)

  Specify the domain of the map, projection is regular longitude/latitude:

  > ! map domain (west east south north): <rcbase>.domain : -30 45 35 75

class cso_catalogue.CSO_GriddedCatalogue(rcfile, rcbase='', env={}, indent='')

  Bases: `CSO_CatalogueBase`

  CSO task to create catalogue of gridded averages of retrievals and simulations.

  The catalogue is created in an output directory specified with:

      <rcbase>.output.dir     :  /Scratch/CSO/catalogue

  A time range for which images should be created is specified with:

      ! specifiy timerange:
      <rcbase>.timerange.start  :  2012-01-01 00:00
      <rcbase>.timerange.end    :  2012-12-31 23:59
      ! step is one of: hour | day | month
      <rcbase>.timerange.step   :  hour

  The time range is used to scan for output files from the `CSO_GriddedAverage` class:

      <rcbase>.input.file        :  /Scratch/model/output/CSO_output_%Y%m%d_%H%M_gridded.nc

  Specify a list of variables to be plotted, for example the retrieved and simulated column:

      <rcbase>.vars                   :  yr ys

  For each variable, define the name of the source variable:

      <rcbase>.var.yr.source               :  yr
      <rcbase>.var.yr.source               :  ys

  Optionally specify a source layer for profiles, default is first layer:

      <rcbase>.var.yr.source_layer         :  0

  Optionally specify target units that are different from the input:

      ! convert units:
      <rcbase>.var.yr.units              :  1e15 mlc/cm2

  The value range of the colorbar could be tunes using (default limits are based on data values):

      <rcbase>.var.vcd.vmin              :   0.0
      <rcbase>.var.vcd.vmax              :  10.0

  The colors in the colorbar could be changed using:

      <rcbase>.var.qa_flag.colors        :   ['red','yellow','green']

  The label below the colorbar will by default show the variable name, unless a `long_name` is defined:

      <rcbase>.var.vcd.long_name         :   retrieved vertical column density

  The name of the created image files is read from:

      ! target files, time tempates are replaced:
      <rcbase>.output.file            :  %Y/%m/%d/S5p_RPRO_NO2_%Y%m%d_%H%M_gridded_%{var}.png

  which will give:

      2020/01/01/CSO_output_20200101_0100_gridded_yr.png
                 CSO_output_20200101_0100_gridded_ys.png
                                                  :

  Enable the following flag to re-create existing files, by default only non-existing files are created:

      <rcbase>.renew                  :  False

  The figures size could be specified to fine tune the shape:

      ! figure size (inches), default is (8,6):
      <rcbase>.figsize             :  (6,6)