Skip to content

Commit f909d43

Browse files
formanforman
authored
Merge pull request #33 from EOPF-Sample-Service/konstntokas-004-add_docuemntation
Documentation added via GitHub Pages
2 parents 2760912 + bc92037 commit f909d43

File tree

7 files changed

+585
-7
lines changed

7 files changed

+585
-7
lines changed

‎README.md‎

Lines changed: 108 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,104 @@
1+
[![Build Status](https://github.com/EOPF-Sample-Service/xcube-eopf/actions/workflows/unit-tests.yml/badge.svg?branch=main)](https://github.com/EOPF-Sample-Service/xcube-eopf/actions)
2+
[![codecov](https://codecov.io/gh/EOPF-Sample-Service/xcube-eopf/branch/main/graph/badge.svg)](https://codecov.io/gh/EOPF-Sample-Service/xcube-eopf)
3+
[![PyPI Version](https://img.shields.io/pypi/v/xcube-eopf)](https://pypi.org/project/xcube-eopf/)
4+
[![Anaconda-Server Badge](https://anaconda.org/conda-forge/xcube-eopf/badges/version.svg)](https://anaconda.org/conda-forge/xcube-eopf)
5+
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v0.json)](https://github.com/charliermarsh/ruff)
6+
[![License](https://anaconda.org/conda-forge/xcube-eopf/badges/license.svg)](https://anaconda.org/conda-forge/xcube-eopf)
7+
8+
19
# xcube-eopf
210

3-
`xcube-eopf` is a Python package and
4-
[xcube plugin](https://xcube.readthedocs.io/en/latest/plugins.html) that adds a
5-
[data store](https://xcube.readthedocs.io/en/latest/api.html#data-store-framework)
6-
named `eopf` to xcube. The data store is used to access ESA EOPF data products as an
11+
`xcube-eopf` is a Python package and [xcube plugin](https://xcube.readthedocs.io/en/latest/plugins.html) that adds a [data store](https://xcube.readthedocs.io/en/latest/api.html#data-store-framework)
12+
named `eopf-zarr` to xcube. The data store is used to access ESA EOPF data products as an
713
analysis-ready datacube (ARDC).
814

15+
## Features
16+
17+
> **IMPORTANT**
18+
> `xcube-eopf` is currently under active development.
19+
> Some features may be partially implemented or still in progress.
20+
21+
The EOPF xcube data store is designed to provide analysis-ready data cubes from the
22+
EOPF Sentinel Zarr samples for Sentinel-1, Sentinel-2, and Sentinel-3 missions. The
23+
main features are summarized below. A more in depth documentation is given in the
24+
[User Guide](guide.md).
25+
26+
Currently, support is focused on **Sentinel-2** products.
27+
28+
29+
### Sentinel-1
30+
31+
Support for Sentinel-1 will be added in an upcoming release.
32+
33+
34+
### Sentinel-2
35+
36+
The current implementation supports two Sentinel-2 product levels, available as
37+
`data_id` values:
38+
39+
- `sentinel-2-l1c`: Level-1C top-of-atmosphere reflectance
40+
- `sentinel-2-l2a`: Level-2A atmospherically corrected surface reflectance
41+
42+
#### Cube Generation Workflow
43+
44+
The workflow for building 3D analysis-ready cubes from Sentinel-2 products involves
45+
the following steps:
46+
47+
1. **Query** products using the [EOPF STAC API](https://stac.browser.user.eopf.eodc.eu/) for a given time range and
48+
spatial extent.
49+
2. **Retrieve** observations as cloud-optimized Zarr chunks via the
50+
[xarray-eopf backend](https://eopf-sample-service.github.io/xarray-eopf/).
51+
3. **Mosaic** spatial tiles into single images per timestamp.
52+
4. **Stack** the mosaicked scenes along the temporal axis to form a 3D cube.
53+
54+
#### Supported Variables
55+
56+
- **Surface reflectance bands**:
57+
`b01`, `b02`, `b03`, `b04`, `b05`, `b06`, `b07`, `b08`, `b8a`, `b09`, `b11`, `b12`
58+
- **Classification/Quality layers** (L2A only):
59+
`cld`, `scl`, `snw`
60+
61+
**Example: Sentinel-2 L2A**
62+
```python
63+
from xcube.core.store import new_data_store
64+
65+
store = new_data_store("eopf-zarr")
66+
ds = store.open_data(
67+
data_id="sentinel-2-l2a",
68+
bbox=[9.7, 53.4, 10.3, 53.7],
69+
time_range=["2025-05-01", "2025-05-07"],
70+
spatial_res=10 / 111320, # meters to degrees (approx.)
71+
crs="EPSG:4326",
72+
variables=["b02", "b03", "b04", "scl"],
73+
)
74+
```
75+
76+
### Sentinel-3
77+
78+
Support for Sentinel-3 products will be added in an upcoming release.
79+
80+
81+
82+
## Usage
83+
84+
The `xcube-eopf` package can be installed from PyPI (`pip install xcube-eopf`)
85+
or conda-forge (`conda install -c conda-forge xcube-eopf`).
86+
After installation, you are ready to go and use the `"eopf-zarr"` argument to initiate
87+
a xcube EOPF data store.
88+
89+
```python
90+
from xcube.core.store import new_data_store
91+
92+
store = new_data_store("eopf-zarr")
93+
ds = store.open_data(
94+
data_id="sentinel-2-l2a",
95+
bbox=[9.7, 53.4, 10.3, 53.7],
96+
time_range=["2025-05-01", "2025-05-07"],
97+
spatial_res=10 / 111320, # meters converted to degrees (approx.)
98+
crs="EPSG:4326",
99+
variables=["b02", "b03", "b04", "scl"],
100+
)
101+
```
9102

10103
## Development
11104

@@ -30,6 +123,17 @@ mamba activate xcube-eopf
30123
pip install -ve .
31124
pytest
32125
```
126+
By default, this will run all unit tests. To run integration tests, use:
127+
128+
```shell
129+
pytest integration
130+
```
131+
132+
To run tests and generate a coverage report, use:
133+
134+
```shell
135+
pytest --cov xcube_eopf --cov-report html tests
136+
```
33137

34138
### Some notes on the strategy of unit-testing
35139

@@ -47,7 +151,6 @@ wants to write cassettes which are not saved already, `--record-mode once` can b
47151
[pytest-recording](https://pypi.org/project/pytest-recording/) supports all records modes given by [VCR.py](https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes).
48152
After recording the cassettes, testing can be performed as usual.
49153

50-
### Documentation
51154

52155
### Setting up a documentation environment
53156

‎docs/about.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# About the `xcube-eopf` project
2+
3+
## Changelog
4+
5+
You can find the complete `xcube-eopf` changelog
6+
[here](https://github.com/EOPF-Sample-Service/xcube-eopf/blob/main/CHANGES.md).
7+
8+
## Reporting
9+
10+
If you have suggestions, ideas, feature requests, or if you have identified
11+
a malfunction or error, then please
12+
[post an issue](https://github.com/EOPF-Sample-Service/xcube-eopf/issues).
13+
14+
## Contributions
15+
16+
The `xcube-eopf` project welcomes contributions of any form
17+
as long as you respect our
18+
[code of conduct](https://github.com/EOPF-Sample-Service/xcube-eopf/blob/main/CODE_OF_CONDUCT.md)
19+
and follow our
20+
[contribution guide](https://github.com/EOPF-Sample-Service/xcube-eopf/blob/main/CONTRIBUTING.md).
21+
22+
If you'd like to submit code or documentation changes, we ask you to provide a
23+
pull request (PR)
24+
[here](https://github.com/EOPF-Sample-Service/xcube-eopf/pulls).
25+
For code and configuration changes, your PR must be linked to a
26+
corresponding issue.
27+
28+
## Development
29+
30+
To install the `xcube-eopf` development environment into an existing Python
31+
environment, do
32+
33+
```bash
34+
pip install .[dev,doc]
35+
```
36+
37+
or create a new environment using `conda` or `mamba`
38+
39+
```bash
40+
mamba env create
41+
```
42+
43+
### Testing and Coverage
44+
45+
`xcube-eopf` uses [pytest](https://docs.pytest.org/) for unit-level testing
46+
and code coverage analysis.
47+
48+
```bash
49+
pytest tests/ --cov=xarray_eopf --cov-report html
50+
```
51+
52+
### Code Style
53+
54+
The `xcube-eopf` source code is formatted and quality-controlled
55+
using [ruff](https://docs.astral.sh/ruff/):
56+
57+
```bash
58+
ruff format
59+
ruff check
60+
```
61+
62+
### Documentation
63+
64+
The `xcube-eopf` documentation is built using the
65+
[mkdocs](https://www.mkdocs.org/) tool.
66+
67+
With repository root as current working directory:
68+
69+
```bash
70+
pip install .[doc]
71+
72+
mkdocs build
73+
mkdocs serve
74+
mkdocs gh-deploy
75+
```
76+
77+
## License
78+
79+
`xcube-eopf` is open source made available under the terms and conditions of the
80+
[Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html).

‎docs/api.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
2+
::: xcube.core.store.new_data_store
3+
::: xcube.core.store.list_data_store_ids
4+
::: xcube.core.store.get_data_store_params_schema
5+
::: xcube_eopf.store.EOPFZarrDataStore
6+
::: xcube.core.store.DataStore
7+
options:
8+
members:
9+
- get_data_ids
10+
- list_data_ids
11+
- has_data
12+
- get_open_data_params_schema
13+
- open_data

0 commit comments

Comments
 (0)