# `cso_superobs` module

The `cso_superobs` module provides classes to create super observations as average of pixels over a regular grid. The result is stored into a `CSO_File` object as if it is a collection of pixels.

## Class hierchy

The classes and are defined according to the following hierchy:

- `UtopyaRc`

  - `CSO_SuperObs`

## Classes

class cso_superobs.CSO_SuperObs(rcfile, rcbase='', env={}, indent='')

  Bases: `UtopyaRc`

  Average pixels over regular grid using rcfile settings.

  The value assigned to a cell is a weighted average of the pixel values, where the weight is relative to the area of the overlapping part. Since a cell might be only partly covered by pixels, the normalization is done using the total overlapping area:

  \[x(i_k,j_k) ~=~ \left(\ \sum\limits_{p\in P_k} y_p\ w_{p,k}\ \right)\ /\ \sum\limits_{p\in P_k}\ w_{p,k}\]

  where:

  - \(i_k,j_k\) are the indices of grid cell \(k\);

  - \(P_k\) is the set of pixels that overlap with cell \(k\);

  - \(y_p\) is the data value of pixel \(p\);

  - \(w_p\) is the footprint area [m2] of pixel \(p\)

  - \(w_{p,k}\) is the area [m2] of pixel \(p\) that overlaps with the cell \(k\).

  The overlapping area is computed using the `LonLatPolygonCentroids` method. This fractions a footprint area into a large number of triangles, and returns for each triangle the centroid and the area. The centroids are collected per grid cell, and sum over the associated triangle area’s is then used as measure for the overlapping area.

  The target grid is regular longitude/latitude and defined using the following settings:

      ! domain definition:
      <rcbase>.west              :  40.0
      <rcbase>.east              :  60.0
      <rcbase>.south             :  20.0
      <rcbase>.north             :  35.0
      ! grid resolution:
      <rcbase>.dlon              :  0.1
      <rcbase>.dlat              :  0.1

  The level recursive splitting of footprint into triangles and assignment of centroids is defined with:

      ! for 4-corner footprints, number of centroids is:
      !  1 (levels=0), 4 (1), 8 (2), 16 (3), 64 (5), 256 (7)
      <rcbase>.mapping.levels         :  7

  A gridded average is created for each orbit within a time range. Specify the time range in the settings using:

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

  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/CSO-data/S5p/OFFL/CH4/Middle-East/%Y/%m/S5p_OFFL_CH4_*.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 the name of the target file; could be useful to include a description of the target grid and the applied filters in the path:

      ! target file, might contain templates:
      !   %Y,%m,etc     : time values
      !   %{basename}   : basename (without extension) of first source file
      <rcbase>.output.file            :   /scratch/CSO-data/S5p/OFFL/CH4/Middle-East_r01x01_qa08/%Y/%m/%{basename}_gridded.nc

  By default all variables are written with `zlib` compression enabled to save storage size. 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:

      ! zlib compression level (default 1, 0 for no compression):
      <rcbase>.output.complevel           :  1

  Existing files are replaced if the following flag is set:

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