Skip to content

Commit 5fb0164

Browse files
authored
Reorganize rules section, add a section on times/durations for accumulated and similar variables (#139)
## Description Add rules for variables requiring references to dates, times, and durations. The existing [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard is used, though because of Standard Name rules we must use lowercase rather than uppercase letters for the time, date, and duration identifiers, unlike the capital letters specified in the standard. Two new suffixes are also added (``_over_T`` and ``_reset_every_T``) to supplement the existing ``_since_T``. In addition, I broke the "ESM Standard Name Rules" section into a few subsections for better organization. ## Issues Resolves #130
1 parent 0a13a57 commit 5fb0164

1 file changed

Lines changed: 49 additions & 17 deletions

File tree

StandardNamesRules.rst

Lines changed: 49 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,9 @@ for use with Earth System Models. It describes the
2121
ESM Standard Name Rules
2222
========================
2323

24+
Constructing names
25+
------------------
26+
2427
#. Standard names should be identical to those from the latest version
2528
of the `Climate and Forecast (CF) metadata
2629
conventions <https://cfconventions.org/standard-names.html>`_ unless
@@ -64,10 +67,34 @@ ESM Standard Name Rules
6467
and ``air_temperature``. When multiple transformations are present, a more detailed description
6568
should be provided in the ``description`` field to prevent any possible ambiguity.
6669

70+
Variable scope
71+
--------------
72+
6773
#. Variables are current and instantaneous unless specified. Variables that are not
6874
current (e.g., previous timestep) or non-instantaneous (e.g., accumulated values)
6975
should have qualifiers in the standard name to describe what they represent.
7076

77+
#. For accumulated variables, or variables representing a change over some period of time, the
78+
following suffixes are available":
79+
80+
* ``over_[time]`` indicates an accumulation or other change over the previous duration/time
81+
* ``reset_every_[date/time]`` an accumulation or other change reset every set duration/time
82+
since the start of the simulation
83+
* ``since_[date/time]`` indicates an accumulation or other change since a given date/time.
84+
85+
Dates, times, and durations should follow the `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`
86+
international standard, modified only to use lowercase rather than uppercase letters. Note that
87+
the standard is slightly different for dates and times vs durations. For example:
88+
89+
* ``accumulated_precipitation_over_pt3h`` accumulated precipitation over the last 3 hours
90+
* ``accumulated_precipitation_over_p1dt12h`` accumulated precipitation over the last 1 day 12 hours
91+
* ``accumulated_precipitation_reset_every_pt1h`` accumulated precipitation reset every 1 hour
92+
* ``accumulated_precipitation_reset_every_p1y`` accumulated precipitation reset every 1 year
93+
* ``accumulated_precipitation_reset_every_p2dt12h`` accumulated precipitation reset every 2 days, 12 hours
94+
* ``accumulated_precipitation_since_20230522t120000`` accumulated precipitation since May 22, 2023 at 12:00
95+
* ``accumulated_precipitation_since_20251225`` accumulated precipitation since December 25, 2025
96+
* ``accumulated_precipitation_since_t00`` accumulated precipitation since 00:00:00 (midnight)
97+
7198
#. By default (when not specified otherwise), variables are grid means or centers
7299
(defined by the host). If a variable is defined at a different physical location,
73100
a qualifier should be used to denote this. For example, to specify the vertical
@@ -92,6 +119,26 @@ ESM Standard Name Rules
92119
``[variable]_at_top_interfaces`` is defined on ``n`` points, and
93120
``[variable]_at_bottom_interfaces`` is defined on ``n`` points.
94121

122+
#. If possible, qualifiers should be limited in order to allow for a wide
123+
applicability of the variable. In other words, don't qualify with ``_for_specific_context``
124+
unless a variable could not conceivably be used outside of the more
125+
narrowly-defined context or a variable without the scope-narrowing qualifiers
126+
already exists and cannot be reused.
127+
128+
**Discouraged:** upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme
129+
130+
**Preferred:** upward_virtual_potential_temperature_flux
131+
132+
#. If there are two identical quantities from different schemes/processes that
133+
need to be kept apart, suitable qualifiers are added to the names of the processes.
134+
If one process is already established and more common than the other, then it is
135+
sufficient to only prefix the new process with a suitable qualifier. Example:
136+
``due_to_convective_GWD`` and ``due_to_convective_whole_atmosphere_GWD``
137+
as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79.
138+
139+
Terminology
140+
-----------
141+
95142
#. By default, *mixing_ratio* refers to mass mixing ratios. The description should
96143
explicitly specify that it refers to the *mass* mixing ratio.
97144
Mass mixing ratios should contain information regarding
@@ -131,23 +178,6 @@ ESM Standard Name Rules
131178
of clouds the variable represents (e.g. *ice_cloud* if only including glaciated clouds, or
132179
*cloud_at_500hPa* if only including clouds that exist at 500 hPa).
133180

134-
#. If possible, qualifiers should be limited in order to allow for a wide
135-
applicability of the variable. In other words, don't qualify with ``_for_specific_context``
136-
unless a variable could not conceivably be used outside of the more
137-
narrowly-defined context or a variable without the scope-narrowing qualifiers
138-
already exists and cannot be reused.
139-
140-
**Discouraged:** upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme
141-
142-
**Preferred:** upward_virtual_potential_temperature_flux
143-
144-
#. If there are two identical quantities from different schemes/processes that
145-
need to be kept apart, suitable qualifiers are added to the names of the processes.
146-
If one process is already established and more common than the other, then it is
147-
sufficient to only prefix the new process with a suitable qualifier. Example:
148-
``due_to_convective_GWD`` and ``due_to_convenctive_whole_atmosphere_GWD``
149-
as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79.
150-
151181
#. Spell out acronyms unless they are obvious to a vast majority of
152182
scientists/developers who may come across them. A list of currently-used
153183
aliases is below. Whenever such an alias exist, use the alias in the
@@ -389,6 +419,8 @@ Suffixes
389419
| on_previous_timestep
390420
| ``N`` _timesteps_back
391421
| since_ ``T``
422+
| over_ ``T``
423+
| reset_every_ ``T``
392424
393425
Computational
394426
-------------

0 commit comments

Comments
 (0)