Metadata-Version: 2.4
Name: xarray-eopf
Version: 0.2.7
Summary: A backend implmentation for xarray that allows for analysis-ready reading of ESA EOPF data products.
Author: Konstantin Ntokas (Brockmann Consult GmbH), Norman Fomferra (Brockmann Consult GmbH)
License: Apache-2.0
Project-URL: Documentation, https://eopf-sample-service.github.io/xarray-eopf
Project-URL: Repository, https://github.com/EOPF-Sample-Service/xarray-eopf
Project-URL: Changelog, https://github.com/EOPF-Sample-Service/xarray-eopf/blob/main/CHANGES.md
Project-URL: Issues, https://github.com/EOPF-Sample-Service/xarray-eopf/issues
Keywords: copernicus,esa,eopf,sentinel,xarray,zarr
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp
Requires-Dist: dask
Requires-Dist: dask-image
Requires-Dist: fsspec
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: pyproj
Requires-Dist: requests
Requires-Dist: s3fs
Requires-Dist: xarray>=2024.10
Requires-Dist: xcube-resampling>=0.3.2
Requires-Dist: zarr
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: hatch; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: jupyterlab; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: doc
Requires-Dist: mkdocs; extra == "doc"
Requires-Dist: mkdocs-autorefs; extra == "doc"
Requires-Dist: mkdocs-material; extra == "doc"
Requires-Dist: mkdocstrings; extra == "doc"
Requires-Dist: mkdocstrings-python; extra == "doc"
Dynamic: license-file

[![Build Status](https://github.com/EOPF-Sample-Service/xarray-eopf/actions/workflows/unit-tests.yml/badge.svg?branch=main)](https://github.com/EOPF-Sample-Service/xarray-eopf/actions)
[![codecov](https://codecov.io/gh/EOPF-Sample-Service/xarray-eopf/branch/main/graph/badge.svg)](https://codecov.io/gh/EOPF-Sample-Service/xarray-eopf)
[![PyPI Version](https://img.shields.io/pypi/v/xarray-eopf)](https://pypi.org/project/xarray-eopf/)
[![Anaconda-Server Badge](https://anaconda.org/conda-forge/xarray-eopf/badges/version.svg)](https://anaconda.org/conda-forge/xarray-eopf)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v0.json)](https://github.com/charliermarsh/ruff)
[![License](https://anaconda.org/conda-forge/xarray-eopf/badges/license.svg)](https://anaconda.org/conda-forge/xarray-eopf)

# xarray-eopf

An [xarray](https://docs.xarray.dev/en/stable/user-guide/io.html) backend implementation
for ESA EOPF data products in Zarr format.

## Features

After installing this package, user can specify a new xarray backend 
named `"eopf-zarr"` to open EOPF sample products. The backend has
two modes of operation, default analysis mode and the native mode. 
Both modes allow 

* to open EOPF sample products from the local filesystem or from their
  original object storage using URLs with both `https` or `s3` 
  protocols;
* to open entire products as `xarray.DataTree` or `xarray.Dataset`; 
* to open a subgroup as `xarray.Dataset`. This works with 
  local filesystem or `s3`-URLs.

The default analysis mode has the aim to represent the EOPF data 
products in an analysis-ready and convenient way. It provides the
following features:

* Open the deeply nested EOPF products as flat `xarray.Dataset` objects.
* All bands and quality images resampled to a single, user provided 
  resolution, hence, spatial dimensions will be just `x` and `y`.
* User-specified resampling by passing interpolation methods for up-scaling
  and aggregation methods for downscaling.
* CF-compliant spatial referencing of datasets using a shared grid 
  mapping variable `spatial_ref`.
* Attach other CF-compliant metadata enhancements such as flag values and 
  meanings for pixel quality information, such as the Sentinel-2 
  scene classification (variable `scl`).

The analysis mode is currently implemented Sentinel-2 products only.
Support for Sentinel-1 and Sentinel-3 is coming soon. 

The native mode does not modify any contents or data, instead it basically 
delegates to the built-in `"zarr"` backend.

More information can be found in the 
[package documentation](https://eopf-sample-service.github.io/xarray-eopf). 

## Usage

The `xarray-eopf` package can be installed from PyPI (`pip install xarray-eopf`)
or conda-forge (`conda install -c conda-forge xarray-eopf`).
Now you can open EOPF sample products using xarray by specifying the
`"eopf-zarr"` backend in your Python code: 

```python

import xarray as xr

s2_l2a_url = (
    "https://stac.browser.user.eopf.eodc.eu/collections/sentinel-2-l2a/"
    "items/S2B_MSIL2A_20250821T084559_N0511_R107_T37VDD_20250821T095143"
)
s2_l2a_dataset = xr.open_dataset(s2_l2a_url, engine="eopf-zarr", resolution=10)
```
 
## Development

### Setting up a development environment

The recommended Python distribution for development is 
[miniforge](https://conda-forge.org/download/) which includes 
conda, mamba, and their dependencies.

```shell
git clone https://github.com/EOPF-Sample-Service/xarray-eopf.git
cd xarray-eopf
mamba env create
mamba activate eopf-xr
pip install -ve .
```

### Install the library locally and test

```shell
mamba activate eopf-xr
pip install -ve .
pytest
```
By default, this will run all unit tests. To run unit tests and generate a coverage 
report, use:

```shell
pytest --cov xarray_eopf --cov-report html tests
```

To run the integration tests, use:  

```shell
pytest integration
```



### Setting up a documentation environment

```shell
mamba activate eopf-xr
pip install .[doc]
```

### Testing documentation changes

```shell
mkdocs serve
```

### Deploying documentation changes

```shell
mkdocs gh-deploy
```
