Introducing modes of operation

.gitignore

@@ -1,3 +1,6 @@
+# Local test data
+/xcube-viewer/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -36,8 +36,15 @@ pytest
 ```
 By default, this will run all unit and integration tests. To run only the unit test
 suite, use:  
+
+```shell
+pytest tests
+```
+
+To run tests and generate a coverage report, use:
+
 ```shell
-pytest tests/
+pytest --cov xarray_eopf --cov-report html tests
 ```
 
 ### Documentation

docs/api.md

@@ -0,0 +1,3 @@
+## Backend API Reference
+
+::: xarray_eopf.backend.EopfBackend

docs/guide.md

@@ -0,0 +1,117 @@
+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 are provided in this mode use a unified grid mapping 
+for all their data variables. This means that selected variables are 
+spatially up-scaled or down-scaled as needed, so that the dataset can use a 
+single shared pair of `x` and `y` coordinates in the returned datasets.
+
+### Function `open_dataset()`
+
+Synopsis:  
+
+```python
+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 `**params`:
+
+- `resolution`: Target resolution for all spatial data variables / bands.
+  Must be one of `10`, `20`, or `60`. 
+- `spline_order`: Spline order to be used for resampling 
+  spatial data variables / bands.
+  Must be one of `0` (nearest neighbor), `1` (linear), `2` (bi-linear), or 
+  `3` (cubic). 
+- `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 `"S2B_MSIL1C"`. 
+  Only required if `filename_or_obj` is not a path or URL 
+  that refers to a product path adhering to EOPF naming conventions.
+
+
+### Function `open_datatree()`
+
+Synopsis: 
+
+```python
+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_datatree()`
+
+Synopsis:  
+
+```python
+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)`.  
+
+### Function `open_dataset()`
+
+Synopsis:  
+
+```python
+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 `**params`:
+
+- `group_sep`: Separator string used to concatenate groups names 
+  to create prefixes for unique variable and dimension names.
+  Defaults to the underscore character (`"_"`).

docs/index.md

@@ -30,11 +30,11 @@ object including groups:
 
 The backend supports two distinct modes of operation, `"native"` and `"analysis-ready"`:
 
-- `mode="native"` - using the _native mode_, the returned `Dataset` or `DataTree`
+- `op_mode="native"` - using the _native mode_, the returned `Dataset` or `DataTree`
   objects try to serve as a 1:1 representation of the actual Zarr product structure and
   content with either none or minimal preprocessing applied.
 
-- `mode="analysis"` - using the _analysis mode_, the returned `Dataset` 
+- `op_mode="analysis"` - using the _analysis mode_, the returned `Dataset` 
   or `DataTree` objects attempt to be user-friendly and analysis-ready to a maximum
   extend. Certain preprocessing steps will be applied depending on the specific 
   Sentinel product towards an analysis-ready data model and content. For example, 

environment.yml

@@ -6,9 +6,12 @@ dependencies:
   # Library Dependencies
   - aiohttp
   - dask
+  - dask-image
   - fsspec
   - numpy
+  - pyproj
   - requests
+  - s3fs
   - xarray >=2024.10
   - zarr >=2,<3.0
   # Development Dependencies - Tools