fcollections.implementations.optional

fcollections.implementations.optional#

Optional functionalities.

Optional functionalities include the geographical selection in the FilesDatabase and IFileReader implementations. Because the dependencies can be heavy, these functionalities are only enabled if we can import shapely, pyinterp and geopandas.

In case this module import fails, the caller should fall back to the default implementations.

Classes

GeoOpenMfDataset(area_selector[, xarray_options])

Extension of the OpenMfDataset reader.

GeoSwotReaderL3WW([xarray_options])

Extension of the SwotReaderL3WW reader.

GeoSwotReaderL2LRSSH([xarray_options])

Extension of the SwotReaderL2LRSSH reader.

GeoSwotReaderL3LRSSH([xarray_options])

Extension of the SwotReaderL3LRSSH reader.

SwotGeometryPredicate(indexes, bbox)

Predicate builder for swot karin footprints.

AreaSelector1D([longitude, latitude])

Abstract Selector for subsetting data on depending on a geographical area, with a 1-dimensional selection.

AreaSelector2D([longitude, latitude])

Selector for subsetting 2d grid data depending on a geographical area.

SwathAreaSelector([longitude, latitude])

Selector for subsetting swath data depending on a geographical area.

TemporalSerieAreaSelector([longitude, ...])

Selector for subsetting temporal series data depending on a geographical area.
class fcollections.implementations.optional.AreaSelector1D(longitude: str = 'longitude', latitude: str = 'latitude')[source]#

Bases: IAreaSelector, ABC

Abstract Selector for subsetting data on depending on a geographical area, with a 1-dimensional selection.

apply(ds: Dataset, bbox: tuple[float, float, float, float]) → Dataset[source]#

Apply a geographical selection on a dataset.

Parameters:

  • ds (xr.Dataset) – a dataset

  • bbox (tuple[float, float, float, float]) – the bounding box (lon_min, lat_min, lon_max, lat_max) used to subset data Longitude coordinates can be provided in [-180, 180[ or [0, 360[ convention. If bbox’s longitude crosses the -180/180 of longitude, data around the crossing and matching the bbox will be selected. (e.g. longitude interval: [170, -170] -> data in [170, 180[ and [-180, -170] will be retrieved)

Return type:

the geographical subset

abstractmethod dims_selection(idx: tuple) → dict[source]#

Build the slice dictionary needed for selecting data subset.

Parameters:

idx (tuple) – indices of data intersecting an area

Return type:

the slice dictionary needed for selecting data subset

class fcollections.implementations.optional.AreaSelector2D(longitude: str = 'longitude', latitude: str = 'latitude')[source]#

Bases: IAreaSelector

Selector for subsetting 2d grid data depending on a geographical area.

The selection is performed on latitude and longitude dimension.

apply(ds: Dataset, bbox: tuple[float, float, float, float]) → Dataset[source]#

Apply a geographical selection on a dataset.

Parameters:

  • ds (xr.Dataset) – a dataset

  • bbox (tuple[float, float, float, float]) – the bounding box (lon_min, lat_min, lon_max, lat_max) used to subset data Longitude coordinates can be provided in [-180, 180[ or [0, 360[ convention. If bbox’s longitude crosses the -180/180 of longitude, data around the crossing and matching the bbox will be selected. (e.g. longitude interval: [170, -170] -> data in [170, 180[ and [-180, -170] will be retrieved)

Return type:

the geographical subset

class fcollections.implementations.optional.GeoOpenMfDataset(area_selector: IAreaSelector, xarray_options: dict[str, str] | None = None)[source]#

Bases: OpenMfDataset

Extension of the OpenMfDataset reader.

Bring geographical awareness to the reader. In case a bounding box is given to the reader, the IAreaSelector is used to update the xarray preprocessor.

Parameters:

  • area_selector – Area selection callable generator

  • xarray_options – xarray.open_mfdataset reading options. Set to None to keep xarray defaults

See also

fcollections.core.IAreaSelector

Interface for defining the area selection callable

xarray.open_mfdataset

The wrapped reading function

read(files: list[str] | list[list[str]], selected_variables: list[str] | None = None, fs: AbstractFileSystem = fs_loc.LocalFileSystem(), bbox: tuple[float, float, float, float] | None = None, preprocess: Callable[[Dataset], Dataset] | None = None, **kwargs: Any) → Dataset[source]#

Read a list of files.

Parameters:

  • files – List of the files to read

  • selected_variables – Variables that needs to be read. Set to None to read everything

  • bbox – the bounding box (lon_min, lat_min, lon_max, lat_max) used to subset data Longitude coordinates can be provided in [-180, 180[ or [0, 360[ convention. If bbox’s longitude crosses the -180/180 of longitude, data around the crossing and matching the bbox will be selected. (e.g. longitude interval: [170, -170] -> data in [170, 180[ and [-180, -170] will be retrieved)

  • fs – File system hosting the files

  • preprocess – Preprocessor for open_mfdataset

Returns:

An xarray dataset containing the selected variables

class fcollections.implementations.optional.GeoSwotReaderL2LRSSH(xarray_options: dict[str, str] | None = None)[source]#

Bases: SwotReaderL2LRSSH

Extension of the SwotReaderL2LRSSH reader.

Bring geographical awareness to the reader. In case a bounding box is given to the reader, the IAreaSelector is used to update the xarray preprocessor.

See also

fcollections.core.IAreaSelector

Interface for defining the area selection callable

read(subset: ProductSubset, files: list[str], selected_variables: list[str] | None = None, fs: AbstractFileSystem = fs_loc.LocalFileSystem(), stack: StackLevel | str = StackLevel.NOSTACK, left_swath: bool = True, right_swath: bool = False, bbox: tuple[float, float, float, float] | None = None) → Dataset[source]#

Read a dataset from L2_LR_SSH products.

Parameters:

  • files – list of files to open. At least one file should be given

  • fs – File systems hosting the files

  • selected_variables – list of variables to select in dataset. Set to None (default) to disable the selection

  • subset – Product dataset (Basic, Expert, WindWave or Unsmoothed)

  • bbox – the bounding box (lon_min, lat_min, lon_max, lat_max) used to select the data in a given area. Longitude coordinates can be provided in [-180, 180[ or [0, 360[ convention. If bbox’s longitude crosses the circularity, it will be split in two subboxes to ensure a proper selection (e.g. longitude interval: [170, -170] -> data in [170, 180[ and [-180, -170] will be retrieved)

  • left_swath – Whether to load the left side of the swath for Unsmoothed datasets. Set to False in conjunction to right_swath will disable swath reading for Expert and Basic dataset

  • right_swath – Whether to load the right side of the swath for Unsmoothed datasets. Set to False in conjunction to right_swath will disable swath reading for Expert and Basic dataset

  • stack – Whether to stack the cycles and passes of the dataset. This option is only available for Basic, Expert and WindWave datasets which are defined on a reference grid (fixed grid between cycles). Set to CYCLES_PASSES to stack both cycles and passes. Set to CYCLES to stack only the cycles, in which case cycles with missing passes will be left over. Defaults to NOSTACK

Raises:

  • ValueError – If the input list of files is empty

  • ValueError – If the input stack parameter is not matching a valid StackLevel

Return type:

An xarray dataset containing the dataset from the input files

class fcollections.implementations.optional.GeoSwotReaderL3LRSSH(xarray_options: dict[str, str] | None = None)[source]#

Bases: SwotReaderL3LRSSH

Extension of the SwotReaderL3LRSSH reader.

Bring geographical awareness to the reader. In case a bounding box is given to the reader, the IAreaSelector is used to update the xarray preprocessor.

See also

fcollections.core.IAreaSelector

Interface for defining the area selection callable

read(subset: ProductSubset, files: list[str] | list[list[str]], selected_variables: list[str] | None = None, fs: AbstractFileSystem = fs_loc.LocalFileSystem(), stack: str | StackLevel = StackLevel.NOSTACK, swath: bool = True, nadir: bool = False, bbox: tuple[float, float, float, float] | None = None) → Dataset[source]#

Read a dataset from L2_LR_SSH products.

Parameters:

  • files – list of files to open. At least one file should be given

  • fs – File systems hosting the files

  • selected_variables – list of variables to select in dataset. Set to None (default) to disable the selection

  • subset – Product dataset (Basic, Expert, Technical or Unsmoothed)

  • bbox – the bounding box (lon_min, lat_min, lon_max, lat_max) used to select the data in a given area. Longitude coordinates can be provided in [-180, 180[ or [0, 360[ convention. If bbox’s longitude crosses the circularity, it will be split in two subboxes to ensure a proper selection (e.g. longitude interval: [170, -170] -> data in [170, 180[ and [-180, -170] will be retrieved)

  • stack – Whether to stack the cycles and passes of the dataset. This option is only available for Basic, Expert and Technical datasets which are defined on a reference grid (fixed grid between cycles). Set to CYCLES_PASSES to stack both cycles and passes. Set to CYCLES to stack only the cycles, in which case cycles with missing passes will be left over. Defaults to NOSTACK

  • nadir – Whether to read the nadir data from the product. Only relevant the Basic and Expert subsets where the nadir data is clipped in the swath. Defaults to False

  • swath – Whether to read the swath data from the product. Only relevant the Basic and Expert subsets where the nadir data is clipped in the swath. Defaults to True

Raises:

  • ValueError – If stack=CYCLES_PASSES or stack=CYCLES, swath=False and nadir=True. In this case, we are trying to stack nadir data which is not guaranteed to have the same number of points per half orbit. This is not supported case

  • ValueError – If swath=False and nadir=False. In this case, the user is asking for an empty return

  • ValueError – If the input list of files is empty

  • ValueError – If the input stack parameter is not matching a valid StackLevel

Returns:

An xarray dataset containing the dataset from the input files

class fcollections.implementations.optional.GeoSwotReaderL3WW(xarray_options: dict[str, str] | None = None)[source]#

Bases: SwotReaderL3WW

Extension of the SwotReaderL3WW reader.

Bring geographical awareness to the reader. In case a bounding box is given to the reader, the IAreaSelector is used to update the xarray preprocessor.

See also

fcollections.core.IAreaSelector

Interface for defining the area selection callable

read(subset: ProductSubset, files: list[str], selected_variables: list[str] | None = None, fs: AbstractFileSystem = fs_loc.LocalFileSystem(), tile: int | None = None, box: int | None = None, bbox: tuple[float, float, float, float] | None = None) → Dataset[source]#

Read a SWOT dataset from LR_SSH products.

Parameters:

  • files – list of files to open. At least one file should be given. If multiple files are given, variables following the n_box dimension will be concatenated. The others variables are constant and will not be repeated

  • fs – File systems hosting the files

  • selected_variables – list of variables to select in dataset. Set to None (default) to disable the selection

  • subset – Product dataset (Light, Extended)

  • bbox – the bounding box (lon_min, lat_min, lon_max, lat_max) used to select the data in a given area. Longitude coordinates can be provided in [-180, 180[ or [0, 360[ convention. If bbox’s longitude crosses the circularity, it will be split in two subboxes to ensure a proper selection (e.g. longitude interval: [170, -170] -> data in [170, 180[ and [-180, -170] will be retrieved)

  • tile – Tile size of the spectrum computation. Is mandatory for the Extended subset

  • box – Box size of the spectrum computation. Is mandatory for the Extended subset if one the requested variables is defined along the n_box dimension

Raises:

  • ValueError – If tile or box argument are given when reading a Light subset

  • ValueError – If the list of files is empty

  • ValueError – If the tile and box argument is missing for the Extended subset

  • ValueError – If the input subset does not match neither Light nor Extended

  • ValueError – If the input tile or box size is not found in the files

Return type:

An xarray dataset containing the dataset from the input files

class fcollections.implementations.optional.SwathAreaSelector(longitude: str = 'longitude', latitude: str = 'latitude')[source]#

Bases: AreaSelector1D

Selector for subsetting swath data depending on a geographical area.

The selection is performed on num_lines dimension.

dims_selection(idx: tuple) → dict[source]#

Build the slice dictionary needed for selecting data subset.

Parameters:

idx (tuple) – indices of data intersecting an area

Return type:

the slice dictionary needed for selecting data subset

class fcollections.implementations.optional.SwotGeometryPredicate(indexes: tuple[int, int], bbox: tuple[float, float, float, float])[source]#

Bases: IPredicate

Predicate builder for swot karin footprints.

This predicate builder can transform a box in a callable that can predict if a given half orbit crosses the box. It uses KaRIn reference footprints for one cycle.

Parameters:

  • indexes – Indexes of the ‘cycle_number’ and ‘pass_number’ element in the input record of the predicate

  • bbox – Bounding box, given as lon_min, lat_min, lon_max, lat_max

classmethod parameters() → tuple[str, ...][source]#

Initialization parameters name for the class.

classmethod record_fields() → tuple[str, ...][source]#

Record fields needed by the predicate.

class fcollections.implementations.optional.TemporalSerieAreaSelector(longitude: str = 'longitude', latitude: str = 'latitude', dimension: str = 'time')[source]#

Bases: AreaSelector1D

Selector for subsetting temporal series data depending on a geographical area.

Parameters:

  • longitude (str) – Name of the longitude variable in the dataset to preprocess

  • latitude (str) – Name of the latitude variable in the dataset to preprocess

  • dimension – Dimension over which the selection is performed (defaults to ‘time’)

dims_selection(idx: tuple) → dict[source]#

Build the slice dictionary needed for selecting data subset.

Parameters:

idx (tuple) – indices of data intersecting an area

Return type:

the slice dictionary needed for selecting data subset

Contents