Features

Features in cerbere implement specific data structures tied to observation patterns shared by many Earth observation data, following the Climate and Forecast conventions (complemented by other conventions or rules). They check and harmonize their dimensions and coordinates so that observations acquired in the same or sharing common spatial and temporal properties are structured and named in the same way.

Feature classes inherit from the main CBaseFeature base class which itself is a wrapper for a Xarray Dataset (and derives from it by composition). They can be created from any Dataset object meeting the expected properties of a given feature. CBaseFeature is an abstract base class and only objects from other classes in feature package can be instantiated. Examples of feature classes include Point, Profile, TimeSeries and many more.

A feature object can therefore be created from any Xarray Dataset object, but it has to match the expected requirements on dimensions and coordinates of the instantiated feature class. cerbere may do some guesses to try to cast the Dataset object into the expected feature class properties, therefore possibly renaming or reorganizing its dimensions and variables.

Reading a feature from a file

Knowing the feature type of an object stored in a file, and the reader class (if not an Xarray engine) corresponding to the file format, one can directly load the content of this file into a fully formed feature object.

In the following example, let’s open a GHRSST L2P file, which is a Swath feature, for which there is a special GHRSST reader class in cerberecontrib-sst contrib package.

In [1]: import cerbere

In [2]: print(cerbere._feature)
---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
Cell In[2], line 1
----> 1 print(cerbere._feature)

AttributeError: module 'cerbere' has no attribute '_feature'

 # detects it is a GHRSST file, fetches the correct reader and returns a
 # CF/Cerbere compliant Swath feature object.
In [3]: swath = cerbere.open_feature(
   ...:      './samples/20190719000110-MAR-L2P_GHRSST-SSTskin-SLSTRA-20190719021531-v02.0-fv01.0.nc',
   ...:      'Swath')
   ...:  print(swath)
   ...: 
  Cell In[3], line 4
    print(swath)
    ^
IndentationError: unexpected indent

Creating a feature from or like a xarray `Dataset` object

Features can be created from a xarray xarray.Dataset object. The definition of the xarray.Dataset object must match the requirements of the feature to be instantiated, in terms of dimensions and coordinate variables.

For instance to create a CylindricalGrid feature from a xarray.Dataset object, the later must have:

lat, lon, time dimensions. time dimension must have a length equal to 1.

a lat coordinate variable with dimension lat.

a lon coordinate variable with dimension lon.

a time coordinate variable with dimension time.

data variables with spatial dimensions (lat, lon,). Extra dimensions are allowed (except time).

from cerbere.feature.cgrid import CylindricalGrid

# create an xarray Dataset with the structure of a cylindrical grid
lat = xr.DataArray(data=np.arange(-80, 80, 1), dims=['lat'])
lon = xr.DataArray(data=np.arange(-180, 180, 1), dims=['lon'])
time = xr.DataArray([datetime(2018, 1, 1)], dims='time')
var = xr.DataArray(
    data=np.ones(shape=(160, 360)),
    dims=['lat', 'lon'],
    attrs={'myattr': 'test_attr_val'}
)
xrdataset = xr.Dataset(
    coords={'lat': lat, 'lon': lon, 'time': time},
    data_vars={'myvar': var},
    attrs={'gattr1': 'gattr1_val', 'gattr2': 'gattr2_val'}
)

# create the cylindrical grid feature from the xarray dataset object
grid = CylindricalGrid(xrdataset)
grid

Harmonization

When creating a feature from a xarray.Dataset object or file content, cerbere performs some checks to verify the object meets the expected feature properties and rename its coordinates and dimensions if necessary.

Available features

The main features currently managed include :

Grid

Swath

Image

GridTimeSeries

Trajectory

PointTimeSeries

Point

Profile

TimeSeries

TimeSeriesProfile

TrajectoryProfile

The classes provided in feature modules and listed above correspond to the main sampling patterns usually used for Earth Observation data. Whenever possible, they follow the recommendations of Climate and Forecast (CF) convention.

The following table describes the dimensions and spatio-temporal coordinate (geolocation) fields associated with each feature in feature:

**cerbere** main features
Feature	Dims [size]	Coords [dims]	Vars [dims]
`Swath`	`row (y)` `cell (x)`	`time (row, cell)` `lat (row, cell)` `lon (row, cell)`	`<name> (row, cell)`
`Image`	`time (1)` `row (y)` `cell (x)`	`time (time)` `lat (row, cell)` `lon (row, cell)`	`<name> (row, cell)`
`Grid`	`time (1)` `y (y)` `x (x)`	`time (time)` `lat (y, x)` `lon (y, x)`	`<name> (y, x)`
`GridTimeSeries`	`time (t)` `y (y)` `x (x)`	`time (time)` `lat (y, x)` `lon (y, x)`	`<name> (time, lat, lon)`
`Point` [1]	`obs (x)`	`time (obs)` `lat (obs)` `lon (obs)` `depth/alt (obs) [opt]`	`<name> (obs)`
`Trajectory` [2]	`time (t)`	`time (time)` `lat (time)` `lon (time)` `depth/alt (time) [opt]`	`<name> (time)`
`Profile` [3]	`profile ()` `z (z)`	`time ()` `lat ()` `lon ()` `alt/depth (z)`	`<name> (z)`
`TimeSeries` [4]	`station (1)` `time (t)`	`time (time)` `lat (time)` `lon (time)` `depth/alt (time) [opt]`	`<name> (time)`
`TrajectoryProfile` [5]	`profile (n)` `z (z)`	`time (profile)` `lat (profile)` `lon (profile)` `alt/depth (profile, z)`	`<name> (profile, z)`
`TimeSeriesProfile` [6]	`profile (n)` `z (z)`	`time (profile)` `lat ()` `lon ()` `alt/depth (profile, z)`	`<name> (profile, z)`

CF references

Special features

Additional types of features, representing particular cases of the main features above, are also available. They follow the CF rules defined for these particular cases, when applicable.

Special features
Feature	Dims [size]	Coords [dims]	Vars [dims]
`UniZTrajectoryProfile` [7]	`profile (n)` `z (z)`	`time (profile)` `lat (profile)` `lon (profile)` `depth/alt (z)`	`<name> (profile, z)`
`CylindricalGrid`	`time (1)` `lat (y)` `lon (x)`	`time (time)` `lat (lat, lon)` `lon (lat, lon)`	`<name> (lat, lon)`

CF references

Collection features

Additional types of features include collection : these are special features that consist in grouping features of the same type into one single dataset along an extra axis, the name of which depends on the grouped feature’s type.

They are described in CF convention and include:

orthogonal multidimensional collection of features (OMDCollection)
incomplete multidimensional collection of features (IMDCollection)
contiguous ragged array collection of features (CRACollection)