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.

An introductory example notebook is available at : - Docs - Intoduction to the xarray EOPF backend - Notebook Gallery - Intoduction to the xarray EOPF backend

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 an EOPF data product from Sentinel-1, -2, or -3 in an analysis-ready, convenient form. Common parameters are:

  • resolution: Target resolution for all spatial data variables / bands.
  • crs: Coordinate reference system of the output dataset. Can be provided as a str or a pyproj.CRS object. If a string is given, it will be parsed using pyproj.crs.CRS.from_string. If not specified, a mission-specific default CRS will be applied (see the respective mission sections below).
  • bbox: Bounding box [west, south, east, north] used for spatial subsetting; coordinates must be in the same CRS as crs.
  • 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.

Additional parameters specific to each Sentinel mission are described below.

Remarks on Specific Sentinel Missions

Sentinel-1

Note: Support for Sentinel-1 GRD products in analysis mode is available. Support for SLC products is planned for a future release.

Sentinel-1 GRD data is provided in radar geometry, defined by the coordinates (azimuth_time, ground_range). To transform this data into an analysis-ready dataset, the following processing steps are applied:

  1. Radiometric Calibration: Raw pixel values (DN) are converted into physically meaningful backscatter values using the beta_nought calibration lookup table (LUT).
  2. Geometric Terrain Correction (GTC): Using a Digital Elevation Model (DEM), the processor performs inverse geocoding by solving the zero-Doppler equation based on satellite orbit information and terrain elevation. This step maps the data from radar geometry to a georeferenced grid.
  3. Radiometric Terrain Correction (RTC): (Optional) RTC compensates for terrain-induced radiometric distortions such as foreshortening, layover, and slope-dependent brightness variations.

📖 D. Small, Flattening Gamma: Radiometric Terrain Correction for SAR Imagery

Supported Products:

Supported Variables

  • Polarization bands:
    vv, vh, hh, hv (each GRD product contains only a subset of these bands)

Specific Sentinel-1 parameters **kwargs:

  • crs: Coordinate reference system of the output dataset. Can be provided as a str or a pyproj.CRS object. If a string is given, it will be parsed using pyproj.crs.CRS.from_string. If not specified, EPSG:4326 is used.
  • resolution: Target resolution for all spatial variables expressed in the units of the specified crs. If not specified, the resolution is derived (in degrees) from the CopDEM (30 m).
  • dem: Digital Elevation Model (DEM) as a CF-compliant xarray.DataArray used for terrain correction. If provided, the parameters crs, bbox, and resolution are ignored, and the target grid is derived from the DEM. If not provided, the CopDEM COG (30 m)
    is automatically retrieved via the CDSE STAC API. This requires CDSE S3 credentials.
  • apply_rtc: Enable or disable radiometric terrain correction (RTC). Default is True.
  • interp_methods: Interpolation method used during GTC and RTC. Supported methods: nearest, bilinear.
  • footprint_scale_factor: Defines how radar pixels contribute to the output grid. Default: (3.0, 3.0), accounting for resolution differences (e.g., ~10 m GRD vs. ~30 m DEM).

Examples:

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:

Supported Variables

  • Surface reflectance bands: b01, b02, b03, b04, b05, b06, b07, b08, b8a, b09, b11, b12
  • Classification/Quality layers (L2A only): cld, scl, snw

Specific Sentinel-2 parameters **kwargs:

  • variables: Select specific spectral bands using the names listed above in Supported Variables. Common spectral band names from the STAC EO extension are also supported for Sentinel-2 analysis mode.
  • crs: Coordinate reference system of the output dataset. Can be provided as a str or a pyproj.CRS object. If a string is given, it will be parsed using pyproj.crs.CRS.from_string. If not specified, the UTM grid of the native data is used.
  • resolution: Target resolution for all spatial variables/bands. Choose 10, 20, or 60 meters to minimize resampling and retain some of the native data resolution.

  • 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. For more information view xcube-resampling Documentation. - 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". For more information view xcube-resampling Documentation.

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.

Examples:

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.

For SLSTR products, a terrain correction is applied during this process. This is necessary because the original geolocation is corrected only for Earth curvature, but not for terrain variability caused by topography. See the SLSTR product description for details.

For OLCI products, no additional terrain correction is required, as it is already incorporated in the Level-1 data. See the OLCI Level-1 product description for details.

Suported Products:

Supported Variables: - sentinel-3-olci-l1-efr: oa01_radiance, oa02_radiance, oa03_radiance, oa04_radiance, oa05_radiance, oa06_radiance, oa07_radiance, oa08_radiance, oa09_radiance, oa10_radiance, oa11_radiance, oa12_radiance, oa13_radiance, oa14_radiance, oa15_radiance, oa16_radiance, oa17_radiance, oa18_radiance, oa19_radiance, oa20_radiance, oa21_radiance - sentinel-3-olci-l2-lfr: gifapar, iwv, otci, rc681, rc865 - sentinel-3-slstr-l1-rbt: s1_radiance_an, s2_radiance_an, s3_radiance_an, s4_radiance_an, s5_radiance_an, s6_radiance_an, s1_radiance_ao, s2_radiance_ao, s3_radiance_ao, s4_radiance_ao, s5_radiance_ao, s6_radiance_ao, s4_radiance_bn, s5_radiance_bn, s6_radiance_bn, s4_radiance_bo, s5_radiance_bo, s6_radiance_bo, f1_bt_fn, f1_bt_fo, f2_bt_in, f2_bt_io, s7_bt_in, s8_bt_in, s9_bt_in, s7_bt_io, s8_bt_io, s9_bt_io - sentinel-3-slstr-l2-lst: lst

Specific Sentinel-3 parameters **kwargs:

  • variables: Select variables using the names listed above in Supported Variables.
  • crs: Coordinate reference system of the output dataset. Can be provided as a str or a pyproj.CRS object. If a string is given, it will be parsed using pyproj.crs.CRS.from_string. If not specified, EPSG:4326 is used.

  • resolution: Target resolution for all spatial variables/bands. If not specified, the default is set per product:

    • Sentinel-3 OLCI Level-1 EFR: 300 meter
    • Sentinel-3 OLCI Level-1 ERR: 1200 meter
    • Sentinel-3 OLCI Level-2 LFR: 300 meter
    • Sentinel-3 SLSTR Level-1 RBT: 500 meter (1000 meter if selected variables come from F- or I-stripe)
    • Sentinel-3 SLSTR Level-2 LST: 1000 meter

    • 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. For more information view xcube-resampling Documentation. - 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". For more information view xcube-resampling Documentation.

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.

Example:

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).

Example: