# Toolbox component definition

## Harmonizer
This package ensures that all datasets can be easily processed by any tool within the CDS toolbox. The main goal of the harmonizer is to return datasets following a common convention, which is as close as possible to the [Climate and Forecast (CF) Metadata Conventions](http://cfconventions.org/).

The `harmonizer` will use `cf-xarray` under the hood, as many features needed have been already implemented:
1. [`guess_coord_axis`](https://cf-xarray.readthedocs.io/en/latest/generated/xarray.Dataset.cf.guess_coord_axis.html): Automagically guess CF axes and coordinates adding missing attributes without modifying existing metadata.
2. [`add_canonical_attributes`](https://cf-xarray.readthedocs.io/en/latest/generated/xarray.Dataset.cf.add_canonical_attributes.html): Add missing CF attributes to variables with a known standard name. Canonical attributes are inferred from the official CF standard name table.
3. [`rename_like`](https://cf-xarray.readthedocs.io/en/latest/generated/xarray.Dataset.cf.rename_like.html): Rename coordinate variables like a template/standard dataset. Note that this step is only needed if downstream tools do not make use of `cf-xarray`.
4. [`units`](https://cf-xarray.readthedocs.io/en/latest/units.html): Downstream packages might use unit-aware arrays (e.g., [`pint`](https://pint.readthedocs.io/) arrays enabled by [`pint-xarray`](https://github.com/xarray-contrib/pint-xarray)). Importing `cf_xarray.units` makes CF-compliant [UDUNITS](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units) compatible with `pint`.

When variables can not be fully described by CF conventions, the `harmonizer` will define custom criteria that are interpreted by `cf-xarray` (see [Custom Criteria](https://cf-xarray.readthedocs.io/en/latest/custom-criteria.html)).

## Downstream tools
TODO

Possible dependencies:
1. [`cf-xarray`](https://cf-xarray.readthedocs.io/en/latest/): `cf-xarray` uses `xarray`’s plugin interface, or "accessor", to provide extensive functionality on `xarray` objects under the `.cf` namespace. `cf-xarray` allows to write generalized code that works on any CF-compliant dataset.
2. [`pint-xarray`](https://pint-xarray.readthedocs.io/en/latest/): A convenience wrapper for using [`pint`](https://pint.readthedocs.io/en/stable/) with `xarray` objects, allowing to define, operate and manipulate physical quantities (i.e., units).

# Main CDS datasets

* ERA5 surface https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels?tab=overview
* ERA5 pressure levels https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-pressure-levels?tab=overview
* ERA5-Land https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-land?tab=overview
* ECV from ERA5 https://cds.climate.copernicus.eu/cdsapp#!/dataset/ecv-for-climate-change?tab=overview
* ORAS5 https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-oras5?tab=overview
* Seasonal forecasts surface https://cds.climate.copernicus.eu/cdsapp#!/dataset/seasonal-original-single-levels?tab=form
* Seasonal forecasts pressure levels https://cds.climate.copernicus.eu/cdsapp#!/dataset/seasonal-original-pressure-levels?tab=overview
* Monthly seasonal forecast https://cds.climate.copernicus.eu/cdsapp#!/dataset/seasonal-monthly-single-levels?tab=form