Skip to content

Add comments to metadata files #162

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mkavulich wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add comments to metadata files #162

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7188827
Fix write_standard_name_table.py to write comments for standard_name …
mkavulich Sep 22, 2026
f2dfc88
Simplify code to pass pylint branches check
mkavulich Sep 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions Metadata-standard-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ The following names are too general to be chosen as standard names, but they can
* `mass_transport`: Movement of some specified mass by advection
* `real`: units = kg s-1
* `mixing_ratio`: A ratio of the amount of one substance to another; when unqualified refers to the ratio of the mass of one substance to the total mass in a given volume
* `comment`: See Standard Name Rules for further details about disambiguation of this term
* `real`: units = kg kg-1
* `mole_flux`: The number of molecules or atoms of a substance traveling through an area per unit time
* `real`: units = mol m-2 s-1
Expand Down Expand Up @@ -173,6 +174,7 @@ These names are used as bases for other names, but may also be considered standa
* `diffuse_vis_albedo`: Albedo of diffuse incident visible radiation
* `real`: units = 1
* `dimensionless_exner_function`: Dimensionless formulation of the Exner function with respect to 1000 hPa
* `comment`: The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp), where p0 is some reference pressure. For the purposes of the standard names, this reference pressure is assumed as 1000 hPa unless specified otherwise; i.e. dimensionless_exner_function_wrt_air_pressure_at_surface would use the surface pressure as P0. Note that this is numerically equivalent to T/theta (temperature divided by potential temperature), where again theta is calculated with respect to 1000 hPa if not specified. Note that this definition is distinct from the dimensional exner_function standard name; see that entry for further comments.
* Equivalent CF name: `dimensionless_exner_function`
* `real`: units = 1
* `direct_nir_albedo`: Albedo of direct incident near-infrared radiation
Expand All @@ -190,6 +192,7 @@ These names are used as bases for other names, but may also be considered standa
* `dry_air_enthalpy_at_constant_pressure`: Specific enthalpy of dry air, h = Cp*T; Cp = Specific heat of dry air at constant pressure, T = temperature
* `real`: units = J kg-1
* `exner_function`: Exner function, cp * (p/p0)^(Rd/cp), where p0 is some reference pressure (1000 hPa if not specified), Rd is the dry air specific gas constant, and cp is the dry air specific heat capacity.
* `comment`: The formulation for the exner function comes in two forms: a dimensional form cp * (p/p0)^(Rd/cp) = cp * (T/theta), and a dimensionless form (p/p0)^(Rd/cp) = (T/theta). In the standard names, we use the unqualified exner_function to refer to the dimensional form, and dimensionless_exner_function to refer to the dimensionless form. See the base name entry for dimensionless_exner_function for further comments.
* `real`: units = 1
* `filename`: Filename
* `character`: units = none
Expand Down Expand Up @@ -246,6 +249,7 @@ These names are used as bases for other names, but may also be considered standa
* Equivalent CF name: `solar_zenith_angle`
* `real`: units = degrees
* `surface_skin_temperature`: The temperature of the shared interface between the surface and the atmosphere
* `comment`: Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'surface_skin_temperature': the temperature of the physical interface of the atmosphere and the surface below. This may be considered equivalent to the radiometric temperature derived from satellite or airborne radiometers, provided a known surface_emissivity, though for water specifically there may be special considerations for measured quantities (see comment on 'sea_surface_skin_temperature'). This definition derives from discussion in Chapter 4 of 'Introduction to Micrometeorology' by S. Pal Arya. This quantity should not be confused with 'skin_temperature_at_toa' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.
* Equivalent CF name: `surface_skin_temperature`
* `real`: units = K
* `temperature_flux`: Flux of temperature across a unit surface
Expand Down Expand Up @@ -273,6 +277,7 @@ These names are used as bases for other names, but may also be considered standa
## Dimensions
Names indicating the size, extent, or bounds of data structures in a model.
* `horizontal_dimension`: Length of the horizontal dimension
* `comment`: In CCPP, horizontal_dimension refers to all horizontal grid columns that an MPI process owns/is responsible for
* `integer`: units = count
* `horizontal_loop_extent`: The horizontal extent of data passed to CCPP physics from the host model during time integration (i.e. in the *run* phase)
* `integer`: units = count
Expand Down Expand Up @@ -303,6 +308,7 @@ Names indicating the size, extent, or bounds of data structures in a model.
* `vertical_dimension_of_surface_snow`: Vertical dimension of surface snow
* `integer`: units = count
* `vertical_interface_dimension`: number of vertical interfaces
* `comment`: an interface is the upper or lower boundary of a model layer. See the rules document for more details about these terms
* `integer`: units = count
* `vertical_interface_dimension_for_radiation`: Vertical interface dimension for radiation
* `integer`: units = count
Expand Down Expand Up @@ -656,6 +662,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts
* `reference_sea_surface_temperature`: Foundation/reference temperature for calculating diurnal ocean temperature changes
* `real`: units = K
* `sea_surface_skin_temperature`: The temperature of the upper layer of sea surface, typically ~10-100 micrometers, as measured by an infrared radiometer
* `comment`: Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'sea_surface_skin_temperature', derived from the CF Standard Names. While there may be some dependence on the IR wavelength used for a measurement, per Donlon et al. (2002) 'Toward Improved Validation of Satellite Sea Surface Skin Temperature Measurements for Climate Research', the difference should not be significant. This quantity should not be confused with 'skin_temperature_at_toa' or 'surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.
* Equivalent CF name: `sea_surface_skin_temperature`
* `real`: units = K
* `sea_surface_temperature`: Sea surface temperature
Expand Down Expand Up @@ -2101,6 +2108,7 @@ Thresholds represent some value at which the behavior of some process changes, i
* `sine_of_solar_declination_angle`: Sine of solar declination angle
* `real`: units = 1
* `skin_temperature_at_toa`: The temperature that a theoretical infinitely thin air layer above the atmosphere would have in radiative equilibrium
* `comment`: Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'skin_temperature_at_toa', which is commonly referred to as simply 'skin_temperature' but top-of-atmosphere is included in the name for clarity and disambiguation. This definition is taken directly from Goessling and Bathiany (2016) 'Why CO2 cools the middle atmosphere - a consolidating model perspective', but very similar definitions can be found broadly in the literature. This quantity should not be confused with 'surface_skin_temperature' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.
* `real`: units = K
* `solar_constant`: Solar constant
* `real`: units = W m-2
Expand Down Expand Up @@ -2286,6 +2294,7 @@ Thresholds represent some value at which the behavior of some process changes, i
* `fine_root_mass_content`: Fine root mass content
* `real`: units = g m-2
* `friction_temperature`: Friction temperature, a.k.a. temperature scale
* `comment`: Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer Scheme' as negative sensible heat flux divided by the product of density, specific heat Cp, and friction velocity u*
* `real`: units = K
* `friction_velocity_for_momentum`: Friction velocity for momentum
* `real`: units = m s-1
Expand Down
55 changes: 55 additions & 0 deletions Metadata-standard-names.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ section:
description: A ratio of the amount of one substance to another; when unqualified
refers to the ratio of the mass of one substance to the total mass in a given
volume
comment: See Standard Name Rules for further details about disambiguation of
this term
type: real
units: kg kg-1
- name: mole_flux
Expand Down Expand Up @@ -309,6 +311,15 @@ section:
cfname: dimensionless_exner_function
description: Dimensionless formulation of the Exner function with respect to
1000 hPa
comment: 'The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp),
where p0 is some reference pressure. For the purposes of the standard names,
this reference pressure is assumed as 1000 hPa unless specified otherwise;
i.e. dimensionless_exner_function_wrt_air_pressure_at_surface would use the
surface pressure as P0. Note that this is numerically equivalent to T/theta
(temperature divided by potential temperature), where again theta is calculated
with respect to 1000 hPa if not specified. Note that this definition is distinct
from the dimensional exner_function standard name; see that entry for further
comments. '
type: real
units: 1
- name: direct_nir_albedo
Expand Down Expand Up @@ -344,6 +355,12 @@ section:
description: Exner function, cp * (p/p0)^(Rd/cp), where p0 is some reference
pressure (1000 hPa if not specified), Rd is the dry air specific gas constant,
and cp is the dry air specific heat capacity.
comment: 'The formulation for the exner function comes in two forms: a dimensional
form cp * (p/p0)^(Rd/cp) = cp * (T/theta), and a dimensionless form (p/p0)^(Rd/cp)
= (T/theta). In the standard names, we use the unqualified exner_function
to refer to the dimensional form, and dimensionless_exner_function to refer
to the dimensionless form. See the base name entry for dimensionless_exner_function
for further comments.'
type: real
units: 1
- name: filename
Expand Down Expand Up @@ -459,6 +476,18 @@ section:
cfname: surface_skin_temperature
description: The temperature of the shared interface between the surface and
the atmosphere
comment: 'Usage of the term ''skin temperature'' varies among different fields
in the literature. In the Standard Names we have adopted what we deem the
most common definition for ''surface_skin_temperature'': the temperature of
the physical interface of the atmosphere and the surface below. This may be
considered equivalent to the radiometric temperature derived from satellite
or airborne radiometers, provided a known surface_emissivity, though for water
specifically there may be special considerations for measured quantities (see
comment on ''sea_surface_skin_temperature''). This definition derives from
discussion in Chapter 4 of ''Introduction to Micrometeorology'' by S. Pal
Arya. This quantity should not be confused with ''skin_temperature_at_toa''
or ''sea_surface_skin_temperature'', which are both sometimes referred to
simply as ''skin_temperature''.'
type: real
units: K
- name: temperature_flux
Expand Down Expand Up @@ -510,6 +539,8 @@ section:
standard_names:
- name: horizontal_dimension
description: Length of the horizontal dimension
comment: In CCPP, horizontal_dimension refers to all horizontal grid columns that
an MPI process owns/is responsible for
type: integer
units: count
- name: horizontal_loop_extent
Expand Down Expand Up @@ -571,6 +602,8 @@ section:
units: count
- name: vertical_interface_dimension
description: number of vertical interfaces
comment: an interface is the upper or lower boundary of a model layer. See the
rules document for more details about these terms
type: integer
units: count
- name: vertical_interface_dimension_for_radiation
Expand Down Expand Up @@ -1292,6 +1325,15 @@ section:
cfname: sea_surface_skin_temperature
description: The temperature of the upper layer of sea surface, typically ~10-100
micrometers, as measured by an infrared radiometer
comment: Usage of the term 'skin temperature' varies among different fields in
the literature. In the Standard Names we have adopted what we deem the most
common definition for 'sea_surface_skin_temperature', derived from the CF Standard
Names. While there may be some dependence on the IR wavelength used for a measurement,
per Donlon et al. (2002) 'Toward Improved Validation of Satellite Sea Surface
Skin Temperature Measurements for Climate Research', the difference should not
be significant. This quantity should not be confused with 'skin_temperature_at_toa'
or 'surface_skin_temperature', which are both sometimes referred to simply as
'skin_temperature'.
type: real
units: K
- name: sea_surface_temperature
Expand Down Expand Up @@ -4377,6 +4419,16 @@ section:
- name: skin_temperature_at_toa
description: The temperature that a theoretical infinitely thin air layer above
the atmosphere would have in radiative equilibrium
comment: Usage of the term 'skin temperature' varies among different fields in
the literature. In the Standard Names we have adopted what we deem the most
common definition for 'skin_temperature_at_toa', which is commonly referred
to as simply 'skin_temperature' but top-of-atmosphere is included in the name
for clarity and disambiguation. This definition is taken directly from Goessling
and Bathiany (2016) 'Why CO2 cools the middle atmosphere - a consolidating
model perspective', but very similar definitions can be found broadly in the
literature. This quantity should not be confused with 'surface_skin_temperature'
or 'sea_surface_skin_temperature', which are both sometimes referred to simply
as 'skin_temperature'.
type: real
units: K
- name: solar_constant
Expand Down Expand Up @@ -4766,6 +4818,9 @@ section:
units: g m-2
- name: friction_temperature
description: Friction temperature, a.k.a. temperature scale
comment: Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer
Scheme' as negative sensible heat flux divided by the product of density, specific
heat Cp, and friction velocity u*
type: real
units: K
- name: friction_velocity_for_momentum
Expand Down
21 changes: 9 additions & 12 deletions tools/write_standard_name_table.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,27 +118,22 @@ def parse_section(snl, sec, level='##'):
snl.write(f'{level} {sec_name}\n')
if sec_comment is not None:
# First, squeeze out the spacing
while sec_comment.find(' ') >= 0:
sec_comment = sec_comment.replace(' ', ' ')
while sec_comment:
sec_comment = sec_comment.lstrip()
cind = sec_comment.find('\\n')
if cind > 0:
snl.write(f'{sec_comment[0:cind]}\n')
sec_comment = sec_comment[cind + 2:]
else:
snl.write(f'{sec_comment}\n')
sec_comment = ''
sec_comment = re.sub(' +', ' ', sec_comment)
for line in sec_comment.split('\\n'):
snl.write(f'{line.strip()}\n')

@climbfuji climbfuji Oct 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for replacing all this gibberish with something that is actually readable.

for std_name in sec:
if std_name.tag == 'section':
parse_section(snl, std_name, level + '#')
continue
stdn_name = std_name.get('name')
stdn_description = std_name.get('description')
stdn_comment = std_name.get('comment')
if stdn_description is None:
sdict = {'standard_name': stdn_name}
stdn_description = standard_name_to_description(sdict)
snl.write(f"* `{stdn_name}`: {stdn_description}\n")
if stdn_comment is not None:
snl.write(f"* `comment`: {stdn_comment}\n")
# Should only be type or cfname as subelements of standard_name
for item in std_name:
if item.tag == 'cfname':
Expand Down Expand Up @@ -194,12 +189,14 @@ def parse_section_for_yaml(section):
stdn_description = standard_name_to_description(sdict)

std_type = std_name.find('type')

std_comment = std_name.get('comment')
std_name_data = OrderedDict()
std_name_data['name'] = stdn_name
if stdn_cfname:
std_name_data['cfname'] = stdn_cfname
std_name_data['description'] = stdn_description
if std_comment is not None:
std_name_data['comment'] = std_comment
if std_type is not None:
std_name_data['type'] = std_type.text

Expand Down
Loading