Skip to content

Add some marine variables #131

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
svahl991 wants to merge 6 commits into
base: main
Choose a base branch
from
+34 −0
Open

Add some marine variables #131

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f7fd6ba
Add some marine variables
svahl991 Dec 31, 2025
2cfaeb5
Update md file
svahl991 Dec 31, 2025
7c9475d
Differentiate between practical and absolute salinity
svahl991 Jan 2, 2026
36f43b1
update md file with script
svahl991 Jan 2, 2026
bd83e9b
Conform to CF naming
svahl991 Jan 2, 2026
c5f139e
Update md file with script
svahl991 Jan 2, 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
10 changes: 10 additions & 0 deletions Metadata-standard-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
* [coordinates](#coordinates)
* [state_variables](#state_variables)
* [land_surface](#land_surface)
* [marine](#marine)
* [diagnostics](#diagnostics)
* [atmospheric_composition](#atmospheric_composition)
* [atmospheric_composition: GOCART aerosols](#atmospheric_composition-gocart-aerosols)
Expand Down Expand Up @@ -544,6 +545,15 @@ Note that appending '_on_previous_timestep' to standard_names in this section yi
* `real`: units = m3 m-3
* `volume_fraction_of_liquid_water_in_soil_at_wilting_point`: volume fraction of water in liquid phase in soil at wilting point
* `real`: units = m3 m-3
## marine
* `potential_temperature_of_sea_water`: sea water potential temperature
* `real`: units = K
Copy link

@Dooruk Dooruk Jan 5, 2026

Choose a reason for hiding this comment

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

I will comment here that while K is used in some products, degC is more common. MOM6 (model SOCA interfaces) outputs model fields in degC. Looking at a few common products I see they differ though, like so:

OISST, SODA, ORAS5 uses degC
EN4, OSTIA (GHRSST) uses K

I guess we can't make up our mind.

Copy link

@twsearle twsearle Jan 6, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

just a note here that GHRSST includes a lot of members from all over the world https://www.ghrsst.org/about-ghrsst/ not just OSTIA (Australian Bureau Of Meterology, NOAA, Canadian Meterological and Oceanographic Society, among many others from elsewhere in Europe etc). See here for a list:
https://www.ghrsst.org/ghrsst-data-services/for-sst-data-producers/ghrsst-catalogue/#/search?from=1&to=30

The GHRSST conventions follow the CF conventions as far as possible with a little extra metadata. Documented in GDS2.1 (page 83, convention is Kelvin for SST variable there).

Copy link
Collaborator

@mkavulich mkavulich Jan 12, 2026

Choose a reason for hiding this comment

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

@Dooruk In the Standard Names dictionary the exact units are not binding, but rather guidelines on the dimensionality of the described quantity (https://github.com/ESCOMP/ESMStandardNames/blob/main/StandardNamesRules.rst#units). We prefer to use SI units wherever possible, since those are standard and unambiguous in their dimensionality, so K is preferred over any other temperature variable here.

* `sea_water_depth`: The depth below the surface of the sea
* `real`: units = m
* `sea_water_salinity`: The salinity of sea water
* `real`: units = ppt m
* `sea_water_temperature`: The temperature of sea water
* `real`: units = K
## diagnostics
* `total_precipitation_rate_at_surface`: Total precipitation rate at surface
* `real`: units = m s-1
Expand Down
18 changes: 18 additions & 0 deletions standard_names.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1000,6 +1000,24 @@
<type units="m3 m-3">real</type>
</standard_name>
</section>
<section name="marine">
<standard_name name="potential_temperature_of_sea_water"
Copy link

@guillaumevernieres guillaumevernieres Jan 5, 2026

Choose a reason for hiding this comment

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

sea_water_potential_temperature to stay consistent with the salinity naming convention that you define below.

Copy link
Collaborator Author

@svahl991 svahl991 Jan 5, 2026

Choose a reason for hiding this comment

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

sea_water_potential_temperature to stay consistent with the salinity naming convention that you define below.

I've commented above on why I have this naming inconsistency.

Copy link

@guillaumevernieres guillaumevernieres Jan 5, 2026

Choose a reason for hiding this comment

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

@svahl991 Oops, sorry, I missed your comment. Should we follow the same convention for salinity then?

Copy link
Collaborator Author

@svahl991 svahl991 Jan 5, 2026

Choose a reason for hiding this comment

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

Should we follow the same convention for salinity then?

Do you mean salinity_of_sea_water instead of sea_water_salinity? I thought about that, but decided it was silly since I don't think you would measure salinity of air. There's a whole list of rules about how to construct ESM names, and the first rule is to use CF names if a good one exists that doesn't cause naming inconsistencies. I feel the CF names for salinity are OK, and right now we're just deciding how many of the CF salinity names to add to ESM, and what units they should have.

Copy link

@guillaumevernieres guillaumevernieres Jan 5, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

FYI @svahl991 : the CF name for sea water potential temperature is sea_water_potential_temperature ... Most of the naming convention in soca attemps to follow CF.

Copy link

@twsearle twsearle Jan 13, 2026

Choose a reason for hiding this comment

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

@climbfuji agreed. I dont think reordering the potential temperature of sea water variable improves clarity or makes the name any different in terms of ambiguity from the cf name. I dont think consistency with atmosphere names is a good reason to deviate from the CF names if we don't need to personally.

Copy link
Collaborator

@climbfuji climbfuji Jan 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

So, the crux is that CF is inconsistent in that regard. You find names like air_temperature but also names like duration_of_sunshine instead of sunshine_duration, or divergence_of_wind instead of wind_divergence. Some names in CF have aliases, allowing both forms, and allow for even more inconsistency with prefices and suffices

atmosphere_mass_content_of_water_vapor
alias: atmosphere_water_vapor_content

One of the goals of ESMStandardNames is to provide a clear framework for how to construct new names. To do that, you need a clear set of rules for how to compose names. After reviewing the names in the CF conventions and the different, inconsistent ways to construct names based on those, we spent considerable effort to decide on one way to compose these names. Consequently, all names in the ESMStandardNames must follow these rules, even if that means that they differ from CF.

The rules are defined in https://github.com/ESCOMP/ESMStandardNames/blob/main/StandardNamesRules.rst. It basically comes down to "what is the base name" and what is a qualifier such as "component", "medium", ...

Looking at the rules and at this particular example, "sea_water_potential_temperature", I can see your point. For one, there is no prefix "potential_temperature" and I would argue that it hardly qualifies as a "component" of a base name. Also, just "sea_water" by itself is not really a base name? Is the base name then sea_water_potential_temperature? I tend to agree, but then I am questioning why the ESMStandardNames dictionary doesn't use air_potential_temperature but potential_temperature_of_air.

The longer you stare at this stuff, the more confusing it gets ...

Copy link
Collaborator

@mkavulich mkavulich Jan 13, 2026

Choose a reason for hiding this comment

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

@climbfuji potential_temperature should be a base name, since it's a distinct quantity from general temperature This was an inadvertent omission; it looks like virtual_potential_temperature made it in but potential_temperature did not.

sea_water in this case is the medium as described in the rules here. But the documentation is very thin here and could probably be expanded/clarified.

Copy link
Collaborator Author

@svahl991 svahl991 Jan 13, 2026

Choose a reason for hiding this comment

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

potential_temperature should be a base name, since it's a distinct quantity from general temperature This was an inadvertent omission;

@mkavulich , So are you suggesting that maybe ESM should be changed to conform to the CF name for air_potential_temperature instead of potential_temperature_of_air. And then it would be consistent to add the CF name sea_water_potential_temperature? I would support this decision.

Copy link
Collaborator

@mkavulich mkavulich Jan 14, 2026

Choose a reason for hiding this comment

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

@svahl991 No, I'm suggesting the opposite. The rules as we currently have them specify that the name should be base_name_[in_medium], though this needs to be updated to include [of_medium] as an option for cases like this where the base name is an inherent property of the medium, not something contained in it (this is something we have discussed before but apparently never got around to adding).

So potential_temperature_of_air and potential_temperature_of_sea_water should be the names conforming to the current standard.

description="sea water potential temperature">
<type units="K">real</type>
</standard_name>
<standard_name name="sea_water_depth"
description="The depth below the surface of the sea">
<type units="m">real</type>
</standard_name>
<standard_name name="sea_water_salinity"
description="The salinity of sea water">
<type units="ppt m">real</type>
Copy link
Collaborator

@gold2718 gold2718 Dec 31, 2025

Choose a reason for hiding this comment

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

I am familiar with ppt for seawater salinity but not ppt m. What is this?

Copy link
Collaborator Author

@svahl991 svahl991 Dec 31, 2025

Choose a reason for hiding this comment

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

I don't know. (I'm a software engineer, not a scientist, so I'm probably not the best person to create this PR.) It could well be incorrect. I just copied the units in use for the existing sea_water_salinity_in_diurnal_thermocline variable, figuring they would have the same units. But, since I don't understand the diurnal_thermocline part, maybe that's incorrect. I'm happy to correct it to just ppt if needed.

Copy link
Collaborator Author

@svahl991 svahl991 Jan 2, 2026

Choose a reason for hiding this comment

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

After a quick google search, it seems like the units for sea_water_salinity should either be ppt (parts per thousand), psu (practical salinity units, which seems to be the same numerical value as ppt), or possibly even just percent. Sorry for not looking into this matter more carefully originally. Can someone with ocean expertise advise on which units should be used here?

Copy link

@travissluka travissluka Jan 2, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

short answer: use PSU, and state "practical salinity of sea water" in the description

long answer:
Technically PSU is not a unit, so i've seen places where the unit is "1", but who cares.
Also, "salinity" is ambiguous, there are 2 main types of salinity 1) "practical salinity" which is what ocean models historically used to use, and is a measure of conductivity and 2) "absolute salinity" which is the more recent standard that models are now starting to use, and has units of g/kg

edit: and, fyi, ppt is close to psu, but technically not the same

Copy link

@Dooruk Dooruk Jan 2, 2026

Choose a reason for hiding this comment

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

We should stick with PSU which is the current standard for measurements. It may be confusing because in Gibbs Seawater (GSW) toolbox, absolute salinity (AS) is used but there is a conversion from pracitcal salinity (PS) to AS.

Copy link
Collaborator Author

@svahl991 svahl991 Jan 2, 2026

Choose a reason for hiding this comment

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

Thanks @travissluka. Since the goal of ESM naming is to avoid ambiguity, should the name of this variable be changed to sea_water_practical_salinity instead of sea_water_salinity? It is possibly only a matter of time until the more recent kind of salinity is added to the ESM naming, so we might as well prepare so we don't have to change names later. Or it is even simple enough to add both names now.

</standard_name>
<standard_name name="sea_water_temperature"
description="The temperature of sea water">
<type units="K">real</type>
</standard_name>
</section>
<section name="diagnostics">
<standard_name name="total_precipitation_rate_at_surface">
<type units="m s-1">real</type>
Expand Down
Loading