add dimensions

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

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.