Skip to content

User Guide

The xarray backend for EOPF data products "eopf-zarr" has two modes of operation, namely analysis mode (the default) and native mode, which are described in the following.

Analysis Mode

This mode aims at representing the EOPF data products in an analysis-ready and convenient form using the xarray data models DataTree and Dataset. For this reason, it is the default mode of operation when using the "eopf-zarr" backend.

The data products provided in this mode use a unified regular grid mapping for all their data variables. This means that selected variables are spatially resampled as needed, so that the dataset can use a single shared pair of 1d x and y coordinates in the returned datasets.

Function open_dataset()

Synopsis: 

dataset = xr.open_dataset(
    filename_or_obj, 
    engine="eopf-zarr", 
    op_mode="analysis", 
    **kwargs
)

Returns a EOPF data product from Sentinel-1, -2, or -3 in a analysis-ready, convenient form. All bands and quality flags are resampled to a unified, user-provided resolution.

Parameters **kwargs:

  • resolution: Target resolution for all spatial data variables / bands.

  • interp_methods: for upsampling / interpolating spatial data variables. Can be a single interpolation method for all variables or a dictionary mapping variable names or dtypes to interpolation method. Supported methods include:

    • 0 (nearest neighbor)
    • 1 (linear / bilinear)
    • "nearest"
    • "triangular"
    • "bilinear"

    The default is 0 for integer arrays (e.g. Sentinel-2 L2A SCL), else 1. - agg_methods: Optional aggregation methods to be used for downsampling spatial data variables / bands. Can be a single method for all variables or a dictionary mapping variable names or dtypes to methods. Supported methods include: "center", "count", "first", "last", "max", "mean", "median", "mode", "min", "prod", "std", "sum", and "var". Defaults to "center" for integer arrays (e.g. Sentinel-2 L2A SCL), else "mean". - variables: Variables to include in the dataset. Can be a name or regex pattern or iterable of the latter. - product_type: Product type name, such as "MSIL1C". Only required if filename_or_obj is not a path or URL that refers to a product path adhering to EOPF naming conventions.

The spatial resampling of datasets is performed using xcube-resampling. Further explanation of the meaning and usage of these parameters for each Sentinel mission is provided in Remarks on Specific Sentinel Missions.

Remarks on Specific Sentinel Missions

Sentinel-1

Support for Sentinel-1 analysis mode will be added in a future release.

Sentinel-2

Sentinel-2 provides multi-spectral imagery at different native resolutions:

  • 10m: b02, b03, b04, b08
  • 20m: b05, b06, b07, b8a, b11, b12
  • 60m: b01, b09, b10

The analysis mode enables resampling between these different resolutions, bringing bands from multiple resolutions onto the same grid using affine transformation via xcube-resampling.

Suported Products:

Specific Sentinel-2 parameters **kwargs:

  • resolution: Target resolution for all spatial data variables / bands. Must be one of 10, 20, or 60.

Examples:
- Example notebook - open-sen2.ipynb
- Notebook gallery - Introduction to xarray-eopf backend
- Webinar 3 - Access EOPF Zarr Products with the New xarray EOPF Backend

Sentinel-3

Sentinel-3 products are provided on their native grid mapping, where each pixel is defined by a latitude/longitude pair, forming a 2D irregular grid.

The analysis mode applies the rectification algorithm in xcube-resampling to transform the irregular dataset into a regular grid with 1D latitude/longitude coordinates.

Suported Products:

Example:
- Example notebook (open-sen3.ipynb)

Function open_datatree()

Synopsis: 

datatree = xr.open_datatree(
    filename_or_obj, 
    engine="eopf-zarr", 
    op_mode="analysis", 
    **kwargs
)

This function is currently not implemented for the analysis mode and will raise a NotImplementedError.

Native Mode

The aim of this mode is to represent EOPF data products without modification using the xarray data models DataTree and Dataset. Content and structure of the original data products are preserved to a maximum extend.

Function open_dataset()

Synopsis: 

dataset = xr.open_dataset(
    filename_or_obj, 
    engine="eopf-zarr", 
    op_mode="native", 
    **kwargs
)

Returns a "flattened" version of the data tree returned by xr.open_datatree() in native mode. Groups are removed by turning their contents into individual datasets and merging them into one. Variables and dimensions are prefixed using their original group paths to make them unique in the returned dataset. For example, the variable b02 found in the group measurements/reflectance/r10m will be renamed to measurements_reflectance_r10m_b02 using the default underscore group separator. The separator character is configurable by setting the group_sep parameter.

The main use case for this function is to allow passing an EOPF data product where the type xr.Dataset is expected (not xr.DataTree) and where the naming of dimensions and variables is not an issue.

Parameters **kwargs:

  • group_sep: Separator string used to concatenate groups names to create prefixes for unique variable and dimension names. Defaults to the underscore character ("_").

Function open_datatree()

Synopsis: 

datatree = xr.open_datatree(
    filename_or_obj, 
    engine="eopf-zarr", 
    op_mode="native", 
    **kwargs
)

Opens a data product as-is including Zarr groups and returns a data tree object.

This function currently returns the result of calling xr.open_datatree(filename_or_obj, engine="zarr", **kwargs).