From b2852367de1af0d84647eb47f452c641cca32e58 Mon Sep 17 00:00:00 2001
From: Paul Eckhardt <pe@nilu.no>
Date: Thu, 22 Aug 2024 16:40:28 +0200
Subject: [PATCH] add dimensions
---
docs/fileformat_netcdf/dimensions.rst | 100 ++++++++++++++++++++++++--
docs/fileformat_netcdf/metadata.rst | 8 ++-
2 files changed, 98 insertions(+), 10 deletions(-)
diff --git a/docs/fileformat_netcdf/dimensions.rst b/docs/fileformat_netcdf/dimensions.rst
index 38cb1d9..819eb98 100644
--- a/docs/fileformat_netcdf/dimensions.rst
+++ b/docs/fileformat_netcdf/dimensions.rst
@@ -2,17 +2,103 @@
Dimensions
**********
+Main dimensions
+===============
+
+The following dimensions are present in every EBAS NetCDF file:
+
+ * ``time``: time dimension for measurement data
+ * ``metadata_time``: time dimension for metadata
+ * ``tbnds``: addirional dimension for :ref:``time boundary variables<time_bnds>``
+
+
+time
+----
+
+The ``time`` dimension represents the time ranges for all measurements in the time
+series of all data variables.
+
+All data variables share the same time dimension and thus contain the same
+measurement intervals.
+
+The ``time`` variable is, following the CF convention defined as follows::
+
+ standard_name: time
+ long_name: time of measurement
+ units: days since 1900-01-01 00:00:00 UTC
+ axis: T
+ calendar: gregorian
+ bounds: time_bnds
+
+Following the CF convention the time variable is defined with the standard name ``time``
+and uses a supported unit specification. CF also requires the calendar attribute and
+recommends the bounds attribute. More on the :ref:`time_bnds` can be found below.
+
+.. _dim_metadata_time:
+
+metadata_time
+-------------
+
+The dimension ``metadata_time`` is used for :ref:`time_dependent_metadata`.
.. _time_bnds:
Time boundaries
---------------
-`boundary variables <http://cfconventions.org/Data/cf-conventions/cf-conventions-1.11/cf-conventions.html#cell-boundaries>`_
+The variables ``time`` and ``metadata_time`` associated with the main dimensions of
+the EBAS NetCDF files contain only timestamps (point in time).
+
+In reality, measurements are performed over a certain time range (e.g. one hour).
+Thus, each measurement has a start and an end time.
+
+The CF convention defines for this problem the concept of
+`boundary variables <http://cfconventions.org/Data/cf-conventions/cf-conventions-1.11/cf-conventions.html#cell-boundaries>`_.
+
+The time axis values (in the ``time`` variable) are set to the midpoint of the
+time ranges for all measuremnts. The additional variable ``time_bnds`` contains
+one more dimension (``tbnds``, length 2) an thus specifies starttime and endtime
+of each measurement.
+
+In analogy, the dimension variabl ``metadata_time`` contains a single timestamp
+(midtime) for each time range with a distinct set of metadata. The associated
+boundary variable ``metadata_time_bnds`` contains an additional dimension
+``tbnds`` (length 2), which contains start- and end times for each metadata
+validity period.
+
+
+Additional dimensions
+=====================
+
+Some parameters in EBAS have additional dimensions, the most prominent are:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Dimension
+ - Description, applies to, example
+ * - Wavelength
+ - For variable which are measured in multiple wavelength, e.g.
+ aerosol_light_scattering_coefficient (nepehlometer), aerosol_absorption_coefficient (filter_absorption_photometer),
+ aerosol_optical_depth (sun_tracking_filter_radiometer).
+ * - Wavelength min, Wavelength max
+ - Same as above, but the wavelengths are specified as max and min, thus adding two additional dimenstions.
+ * - Wavelength 1, Wavelength 2
+ - For aerosol_absorption_angstrom_exponent calculated between two wavenelgths.
+ * - D
+ - Particle diameter (size bins), e.g, for particle_number_size_distribution.
+ * - Dmin, Dmax
+ - Same as above, but the size bins are defined with an upper and lower size, thus adding two additional dimenstions.
+ * - Tower inlet height
+ - Tower measurements performed in different heights.
+ * - Profile height
+ - aerosol_extinction_coefficient (maxdoas)
+ * - RH, RH base, RH base max, RH humidified
+ - aerosol_light_(back)scattering_coefficient as a function of rH.
+ * - SS
+ - Supersaturaion (%), for cloud_condensation_nuclei_number_concentration
+ * - Location
+ - Location of measurements, used for auxiliary data. E.g. temperature, pressure or humidity measured at different points in the sample line.
+ E.g. temperature, Location=inlet; temperature, Location=instrument inlet; temperature, Location=instrument internal; temperature, Location=sheath air loop
+
- * time
- * metadata time
- * additional dimensions
- * Location (instrument inlet etc..)
- * Wavelength
- * D
diff --git a/docs/fileformat_netcdf/metadata.rst b/docs/fileformat_netcdf/metadata.rst
index c5e5b7e..3fad768 100644
--- a/docs/fileformat_netcdf/metadata.rst
+++ b/docs/fileformat_netcdf/metadata.rst
@@ -76,6 +76,8 @@ Metadata will appear in three different places:
gen_ebas_metadata.rst
+.. _time_dependent_metadata:
+
Time depenendent metadata
=========================
@@ -90,13 +92,13 @@ can be written to a single NetCDF file.
Implementation
--------------
-Time dependent metadata are implemented as additional variable for each data
-variable, named like the main variable name with a postfix ``_ebasmetadata``.
+Time dependent metadata are implemented as an additional variable for **each data
+variable**, named like the main variable name with a postfix ``_ebasmetadata``.
The data type for the metadata variables is string and it contains a set of all ebas
metadata for the specific time range as json encoded string.
-There is a dedicated time dimension for all metadata changes, called ``metadata_time``.
+There is a dedicated time dimension for all metadata changes, called :ref:``metadata_time<dim_metadata_time>``.
This should not be confused with the ``time`` dimension used for the measurement data.
The ``time`` dimension has usually a length of > 1000 (one for each measurment interval),
the ``metadata_time`` dimension has typically only a length of < 10, one for each change of metadata.
--
GitLab