From fcd7d63cf1681b7690e1c5da6a7270545e86e069 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mika=20Pfl=C3=BCger?= Date: Tue, 22 Oct 2024 15:23:07 +0200 Subject: [PATCH] docs: remove sec_cats from documentation --- .../source/data_format/data_format_details.md | 20 +++++++++---------- .../data_format/data_format_examples.md | 10 +++------- .../interchange_format_examples.md | 3 --- 3 files changed, 13 insertions(+), 20 deletions(-) diff --git a/docs/source/data_format/data_format_details.md b/docs/source/data_format/data_format_details.md index cf73ef2b..597a650c 100644 --- a/docs/source/data_format/data_format_details.md +++ b/docs/source/data_format/data_format_details.md @@ -12,16 +12,16 @@ For all dimensions, defined names have to be used and additional metadata about dimensions is stored in the datasets `attrs`. The dimensions are: -| dimension | dimension key | req. | notes | attrs | -|-----------------|-----------------------|------|---------------------------|---------------------------------------| -| time | time | ✗ | for periods, the start | | -| area | area () | ✗ | pre-defined category sets | `'area': 'area ()'` | -| category | category () | | primary category | `'cat': 'category ()'` | -| sec. categories | () | | there can be multiple | `'sec_cats': [' ()', …]` | -| scenario | scenario () | | | `'scen': 'scenario ()'` | -| provenance | provenance | | values from fixed set | | -| model | model | | | | -| source | source | ✗ | a short source identifier | | +| dimension | dimension key | req. | notes | attrs | +|-----------------|-------------------------|------|---------------------------|-----------------------------------| +| `time` | `time` | ✗ | for periods, the start | | +| `area` | `area ()` | ✗ | pre-defined category sets | `'area': 'area ()'` | +| `category` | `category ()` | | primary category | `'cat': 'category ()'` | +| sec. categories | ` ()` | | there can be multiple | | +| `scenario` | `scenario ()` | | | `'scen': 'scenario ()'` | +| `provenance` | `provenance` | | values from fixed set | | +| `model` | `model` | | | | +| `source` | `source` | ✗ | a short source identifier | | For some dimensions, the meaning of the data is directly visible from the data type (`time` uses an xarray datetime data type) or the values come from a pre-defined list diff --git a/docs/source/data_format/data_format_examples.md b/docs/source/data_format/data_format_examples.md index 5295c8ad..02757953 100644 --- a/docs/source/data_format/data_format_examples.md +++ b/docs/source/data_format/data_format_examples.md @@ -138,7 +138,6 @@ opulent = xr.Dataset( "entity_terminology": "primap2", "area": "area (ISO3)", "cat": "category (IPCC 2006)", - "sec_cats": ["animal (FAOSTAT)", "product (FAOSTAT)"], "scen": "scenario (FAOSTAT)", "references": "doi:10.1012", "rights": "Use however you want.", @@ -205,11 +204,8 @@ Compared to the minimal example, this data set has a lot more to unpack: specific set of categories given in parentheses and with appropriate metadata in the `attrs`. The `scenario` is a standard dimension, and the metadata in `attrs` is given using - the `scen` key. The `animal` and `product` dimensions are nonstandard, and are - included in the - secondary categories at `attrs['sec_cats']`. Note that `sec_cats` contains a list, so - that multiple nonstandard dimensions can be included if needed. -* There is also s coordinate which is not defining a dimensions, `category names`. It + the `scen` key. The `animal` and `product` dimensions are nonstandard. +* There is also a coordinate which is not defining a dimension, `category names`. It gives additional information about categories, which can be helpful for humans trying to make sense of the category codes without looking them up. Note that because this coordinate is not used as an index for a dimension, the category @@ -218,7 +214,7 @@ Compared to the minimal example, this data set has a lot more to unpack: the population data does not use all dimensions. For each data variable, only the dimensions which make sense have to be used. * In the `attrs`, the terminology for the entities is explicitly defined, so that the - meaning of the entity attributes is unambigously defined. + meaning of the entity attributes is unambiguously defined. * In the `attrs`, additional metadata useful for humans is included: citable `references`, usage `rights`, a descriptive `title`, a long-form `comment`, an email address to `contact` for questions about the data set, and the `publication_date`. diff --git a/docs/source/data_format/interchange_format_examples.md b/docs/source/data_format/interchange_format_examples.md index 54ac9ae8..2afd8fcc 100644 --- a/docs/source/data_format/interchange_format_examples.md +++ b/docs/source/data_format/interchange_format_examples.md @@ -52,9 +52,6 @@ They are listed as secondary columns in the metadata dict. Column names correspond to the dimension key of the xarray format, i.e. they contain the terminology in parentheses (e.g. `area (ISO3)`). -Additional columns are currently not possible, but the option will be added -in a future release ([#25](https://github.com/pik-primap/primap2/issues/25)). - The metadata dict has an `attrs` entry, which corresponds to the `attrs` dict of the xarray format (see [Data format details](data_format_details.md)). Additionally, the metadata dict contains information on the `dimensions` of the