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 all 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
12 changes: 12 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,17 @@ 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 practical salinity of sea water
* `real`: units = PSU
* `sea_water_absolute_salinity`: The absolute salinity of sea water
* `real`: units = g kg-1
* `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
22 changes: 22 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,28 @@
<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
Collaborator

@climbfuji climbfuji Jan 13, 2026

Choose a reason for hiding this comment

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

The ESM (Earth System Model) standard names were created to provide consistency between Earth system models. While the original effort started with CF names only, it became clear very quickly that these wouldn't suffice. Hence, the next step was to add names where no CF names existed. It then became obvious that the CF names in some cases were inconsistent, misleading, or unclear, and that using the CF names would make it difficult to achieve the goals of the ESM standard names effort. At this point, it was decided that CF would be used, when possible, but that a deviation from the standard is acceptable otherwise.

Names in ESM standard names apply to all modeling systems using these names. That is, they are not model specific, and they provide compatibility and clarity across systems that use the ESM standard names, beyond what the sometimes ambiguous and extremely limited CF convention would be able to do.

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.

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 practical salinity of sea water">
<type units="PSU">real</type>
</standard_name>
<standard_name name="sea_water_absolute_salinity"
description="The absolute salinity of sea water">
<type units="g kg-1">real</type>
</standard_name>
Comment on lines +1012 to +1019
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.

I took a look at the CF conventions, and added their names for these two quantities. It looks to me like CF uses ppt, not PSU for the units of sea_water_salinity. But I stuck with PSU here since that is what @Dooruk and @travissluka recommended.

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.

OK, I looked again, closer, and CF naming has three names:

  • sea_water_salinity with units of 1e-3 (which I think means the same as ppt?)
  • sea_water_practical_salinity with units of 1 (which Travis says is the same as PSU)
  • sea_water_absolute_salinity with units of g kg-1

Do we want to duplicate all three names in ESM? I need scientific guidance here.

Copy link

@lren20 lren20 Jan 5, 2026

Choose a reason for hiding this comment

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

@Dooruk referred me to this issue.
Here are my suggestions and perspective on this issue:

sea_water_salinity with units of 1e-3 (which I believe is equivalent to ppt): I don’t think it is necessary to keep this variable, as it reflects an older and less precise definition of salinity.

sea_water_practical_salinity with units of 1 (which Travis noted is equivalent to PSU): This variable should be retained, as it is consistent with in-situ observations and is useful for validation and diagnostic analyses.

sea_water_absolute_salinity with units of g kg⁻¹: This represents the most recent and precise definition of salinity and is therefore also worth keeping.

If only one salinity variable were to be retained, I would lean toward sea_water_absolute_salinity, assuming it comes directly from the model output.

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.

Thanks, @lren20 , for your insights. That's very helpful. Since these variables are all new to this ESM naming standard, we are free to do what makes sense and is clear for the modern community. We can look to CF naming for insight, but don't need to be constrained by it. Given what you've said, I propose we add two salinity names to ESM Naming in this PR:

  1. Either sea_water_salinity or sea_water_practical_salinity, with units of PSU either way. Going with sea_water_salinity probably means fewer changes in legacy code, but we would be changing the units for this name from the CF convention, so we're possibly introducing some confusion there. Conversely, using sea_water_practical_salinity for the ESM name conforms to the CF standard and is completely unambiguous, but probably requires more changes to legacy code, since then sea_water_salinity will not be an ESM name.
  2. Also add the name sea_water_absolute_salinity with units of g kg-1, since this is the most recent and precise salinity definition.

Regarding the two options described in 1) above, currently this PR contains sea_water_salinity with units of PSU. I'm now leaning toward changing this name to sea_water_practical_salinity. Then the ESM names would be consistent with CF, but would be missing the older, somewhat ambiguous term sea_water_salinity.

I will make that change later today unless I hear objections.

Copy link

@Dooruk Dooruk 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.

  1. I would rather stick with sea_water_practical_salinity but that would require SOCA changes and potential downstream impacts for EMC and GMAO.
  2. Sounds good

i will ask @sinakhani and @guillaumevernieres input here (please see temperature unit comment above as well).

@ss421 I see this turned out to be a can of worms, we could also discuss it during the Thursday JCSDA meeting?

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.

I would rather stick with sea_water_practical_salinity but that would require SOCA changes and potential downstream impacts for EMC and GMAO.

To be clear, it is only in JEDI generic code (such as VADER, SABER, and UFO) where we make a strong attempt to conform to using ESM names for the model variables. This is because it is most important in generic code to be clear and unambiguous about what the variables represent (and what units they have) since the code can be used by multiple models and organizations. So if, say, we choose to use the ESM name sea_water_practical_salinity in the VADER code, that doesn't mean all of SOCA needs to change all its code to using that name. It just means SOCA will need to do a variable name change when it passes the variable into VADER. This sort of thing is done in multiple model interfaces to JEDI.

We also need to make sure we know which salinity units are appropriate for the new VADER code that inspired this PR (referenced in the PR description), so that we are sure to have an appropriate name for use there. (i.e., if the code formulas in VADER are expecting salinity to be in ppt, then we better have a name with those units.)

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.

Ok thanks, that separation makes more sense now.

Copy link

@sinakhani sinakhani Jan 5, 2026

Choose a reason for hiding this comment

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

I think [ppt] is identical to [g/kg] based on their definitions. If I am also not wrong, 1 PSU should approximately equal to 1 ppt in oceanography (PSU is more recent definition for salinity but ppt is an older one). I expect all these three variables to be very close -- are they very different in your data outputs?

For temperature, I think it is a choice to use degC or K since they only differ by a constant 273.15. As long as the dataset gives a unit for temperature, either choice is fine in my view.

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.

From a met office marine obs perspective, we use all three. But our models use only two 'sea_water_salinity' for EOS80 salinity, and 'sea_water_absolute_salinity' for TEOS-10 salinity.

https://www.teos-10.org/

<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