Add some marine variables #131

svahl991 · 2025-12-31T18:21:45Z

Description

We need some marine variables added to the ESM standard since we wish to use them in generic JEDI code for use with SOCA. I have attempted to follow the conventions used for the corresponding air variables.

Issues

Variables needed for https://github.com/JCSDA-internal/vader/pull/208

svahl991 · 2025-12-31T18:51:41Z

Tagging @travissluka, @shlyaeva, @Dooruk

svahl991 · 2025-12-31T18:59:16Z

There's a failing check on this PR that should be resolved by commit 2cfaeb5, but the test didn't get re-triggered.

svahl991 · 2025-12-31T19:03:15Z

Note that I'm aware of the apparent inconsistency between adding the names potential_temperature_of_sea_water and sea_water_temperature (instead of temperature_of_sea_water). But I was attempting consistency with the corresponding air variables, which are named in this inconsistent way as well.

gold2718

I have a question about units but this otherwise seems fine.

gold2718 · 2025-12-31T19:21:04Z

standard_names.xml

+    </standard_name>
+    <standard_name name="sea_water_salinity"
+                   description="The salinity of sea water">
+       <type units="ppt m">real</type>


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

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.

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?

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

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.

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.

svahl991 · 2026-01-02T17:18:55Z

Tagging @twsearle

svahl991 · 2026-01-02T19:16:18Z

standard_names.xml

+    <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>


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.

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.

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

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:

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.

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.

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

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?

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.)

Ok thanks, that separation makes more sense now.

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.

Dooruk · 2026-01-05T21:06:58Z

Metadata-standard-names.md

    * `real`: units = m3 m-3
+## marine
+* `potential_temperature_of_sea_water`: sea water potential temperature
+    * `real`: units = K


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.

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).

guillaumevernieres · 2026-01-05T21:30:17Z

standard_names.xml

    </standard_name>
  </section>
+  <section name="marine">
+    <standard_name name="potential_temperature_of_sea_water"


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

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.

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

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.

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.

ESM naming has diverged from CF naming in some aspects. I notice that CF has air_potential_temperature and ESM has potential_temperature_of_air. Whatever the reasoning was for that divergence, I suspect it would apply to sea water as well. I know this causes inconvenience for models using CF naming. I don't know what the reasoning was for this divergence, but I know a lot of discussion went into it.

just to say, met office marine models have already been using the sea_water_potential_temperature CF names for multiple years. I think we notified that we wanted these in these standards a few years ago? CF standard names would be preferred if you want to share with other modelling centers? @svahl991 has a spreadsheet with the names we discussed on it somewhere I think.

just to say, met office marine models have already been using the sea_water_potential_temperature CF names for multiple years. I think we notified that we wanted these in these standards a few years ago? CF standard names would be preferred if you want to share with other modelling centers? @svahl991 has a spreadsheet with the names we discussed on it somewhere I think.

+1 to @twsearle 's post above, keeping the CF name would be preferential.

Add some marine variables

f7fd6ba

svahl991 self-assigned this Dec 31, 2025

svahl991 requested review from MarekWlasak, cacraigucar, climbfuji, dustinswales, gold2718, grantfirl, mkavulich, mwaxmonsky, nusbaume, peverwhee and ss421 as code owners December 31, 2025 18:21

Update md file

2cfaeb5

gold2718 approved these changes Dec 31, 2025

View reviewed changes

svahl991 added 4 commits January 2, 2026 10:52

Differentiate between practical and absolute salinity

7c9475d

update md file with script

36f43b1

Conform to CF naming

bd83e9b

Update md file with script

c5f139e

svahl991 commented Jan 2, 2026

View reviewed changes

Dooruk reviewed Jan 5, 2026

View reviewed changes

guillaumevernieres reviewed Jan 5, 2026

View reviewed changes

Add some marine variables #131

Are you sure you want to change the base?

Add some marine variables #131

Conversation

svahl991 commented Dec 31, 2025

Description

Issues

Uh oh!

svahl991 commented Dec 31, 2025

Uh oh!

svahl991 commented Dec 31, 2025

Uh oh!

svahl991 commented Dec 31, 2025

Uh oh!

gold2718 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

travissluka Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

svahl991 commented Jan 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Dooruk Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

twsearle Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guillaumevernieres Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

travissluka Jan 2, 2026 •

edited

Loading

Dooruk Jan 5, 2026 •

edited

Loading

twsearle Jan 6, 2026 •

edited

Loading

guillaumevernieres Jan 5, 2026 •

edited

Loading