From fe20691950aaaaae7bb7036d578cc7b5ee728582 Mon Sep 17 00:00:00 2001 From: konstntokas Date: Wed, 16 Apr 2025 12:38:53 +0200 Subject: [PATCH] docu updated --- docs/api.md | 1 - docs/guide.md | 40 +++++++++++++++++++++------------------- docs/index.md | 34 +++++++++++++++++++++++----------- docs/start.md | 8 ++++---- 4 files changed, 48 insertions(+), 35 deletions(-) diff --git a/docs/api.md b/docs/api.md index d9a9847..4933f90 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,3 +1,2 @@ -## Backend API Reference ::: xarray_eopf.backend.EopfBackend diff --git a/docs/guide.md b/docs/guide.md index 2d049a5..105e7ab 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -9,7 +9,7 @@ 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 +The data products 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. @@ -67,24 +67,6 @@ 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: @@ -115,3 +97,23 @@ 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 (`"_"`). + + +### 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)`. + diff --git a/docs/index.md b/docs/index.md index 1028aae..4abbbe9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,24 +1,24 @@ # EOPF xarray backend `xarray-eopf` is a Python package that enhances [xarray](https://docs.xarray.dev/en/stable/user-guide/io.html) by a new backend -named `"eopf-zarr"`. This backend allows for reading the ESA EOPF data products +named `"eopf-zarr"`. This backend allows for reading the [ESA EOPF data](https://eopf.copernicus.eu/eopf-products-and-adfs/) products in Zarr format and representing them using analysis ready data models. ## Overview After installation of the package, you can open EOPF data products using the usual xarray top-level functions `open_dataset()` that provides -a [`Dataset`](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html) object +a [`Dataset`](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html) object: ```python - dataset = xr.open_dataset(url_or_path_to_product, engine="eopf-zarr") +dataset = xr.open_dataset(url_or_path, engine="eopf-zarr") ``` and `open_datatree()` that provides a [`DataTree`](https://docs.xarray.dev/en/stable/generated/xarray.DataTree.html) object including groups: ```python - datatree = xr.open_datatree(url_or_path_to_product, engine="eopf-zarr") +datatree = xr.open_datatree(url_or_path, engine="eopf-zarr") ``` ## Features @@ -28,11 +28,7 @@ object including groups: > The following features are only partly or not at all implemented yet. -The backend supports two distinct modes of operation, `"native"` and `"analysis-ready"`: - -- `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. +The backend supports two distinct modes of operation, `"native"` and `"analysis"`: - `op_mode="analysis"` - using the _analysis mode_, the returned `Dataset` or `DataTree` objects attempt to be user-friendly and analysis-ready to a maximum @@ -40,7 +36,23 @@ The backend supports two distinct modes of operation, `"native"` and `"analysis- Sentinel product towards an analysis-ready data model and content. For example, for Sentinel-2, we will support the selection of specific bands and resampling to a desired spatial resolution. For Sentinel-3 we will allow for rectifying the images - in satellite coordinates to a user-provided, common CRS. + in satellite coordinates to a user-provided, common CRS. It can be used as shown + in the examples below: +```python +dataset = xr.open_dataset(url_or_path, engine="eopf-zarr", op_mode="analysis") +datatree = xr.open_datatree(url_or_path, engine="eopf-zarr", op_mode="analysis") +``` + +- `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. It can be used as shown + in the examples below: +```python +dataset = xr.open_dataset(url_or_path, engine="eopf-zarr", op_mode="native") +datatree = xr.open_datatree(url_or_path, engine="eopf-zarr", op_mode="native") +``` + +More information on the two modes are given in the [User Guide](guide.md) Data variables will always be represented as chunked Dask arrays for efficient out-of core computations and visualisations. @@ -49,7 +61,7 @@ The package has minimal core dependencies: `xarray`, `zarr`, and `dask`. Packages for accessing remote filesystems are optional, e.g., you will need `s3fs` if you need to access EOPF data products in S3-compatible remote object storages. -### License +## License The package is open source and released under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html) license. :heart: diff --git a/docs/start.md b/docs/start.md index e4b4faa..89173c7 100644 --- a/docs/start.md +++ b/docs/start.md @@ -1,6 +1,6 @@ # Getting Started -By installing the `xarray-eopf` package into an existing Python environment +The `xarray-eopf` package can be installed into an existing Python environment using ```bash @@ -13,11 +13,11 @@ or conda install -c conda-forge xarray-eopf ``` -you are ready to go and use the `engine="eopf-zarr"` keyword argument when calling -`open_dataset()` or `open_datatree()`: +After installation, you are ready to go and use the `engine="eopf-zarr"` keyword +argument when calling `open_dataset()` or `open_datatree()`: ```python import xarray as xr -dataset = xr.open_dataset(url_or_path_to_product, engine="eopf-zarr") +dataset = xr.open_dataset(url_or_path, engine="eopf-zarr") ```