CF Metadata: Ticket #93: Two new dimensionless vertical coordinate specifications for s coordinate ocean models
https://cf-trac.llnl.gov/trac/ticket/93
<h2 id="a1.Title">1. Title</h2>
<p>
Two new dimensionless vertical coordinates to support ocean models
</p>
<h2 id="a2.Moderator">2. Moderator</h2>
<p>
Rich Signell
</p>
<h2 id="a3.Requirement">3. Requirement</h2>
<p>
The ocean modeling community needs two additional vertical coordinate specifications to allow modern s-coordinate model output to be CF-compliant and allow more general specification of s-coordinate model output for future development.
</p>
<h2 id="a4.InitialStatementofTechnicalProposal">4. Initial Statement of Technical Proposal</h2>
<p>
The existing ocean_s_coordinate dimensionless vertical coordinate specification in CF is limited to a specific vertical stretching function and set of control parameters, while modern versions of ROMS allow for more flexible specification. Additional of these two new generalized vertical coordinate specifications would allow output from existing ROMS-derived models (and other s coordinate models) to be CF-compliant, as well as allowing more flexibility for future s_coordinate model developers and users to write and read CF-compliant model output.
</p>
<p>
Here are the proposed additions to Appendix D. Dimensionless Vertical Coordinates
</p>
<p>
<strong>Ocean s-coordinate, generic form 1</strong>
</p>
<pre class="wiki"> standard_name = "ocean_s_coordinate_g1"
</pre><blockquote>
<p>
Definition:
</p>
<pre class="wiki"> z(n,k,j,i) = S(k,j,i) + eta(n,j,i) * (1 + S(k,j,i) / depth(j,i))
where S(k,j,i) = depth_c * s(k) + (depth(j,i) - depth_c) * C(k)
</pre></blockquote>
<p>
and where z(n,k,j,i) is the height, positive upwards, relative to
ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i);
eta(n,j,i) is the height of the ocean surface, positive upwards,
relative to ocean datum at gridpoint (n,j,i); s(k) is the
dimensionless coordinate at vertical gridpoint (k) with a
range of -1 <= s(k) <= 0, s(0) corresponds to eta(n,j,i) whereas
s(-1) corresponds to depth(j,i); C(k) is the dimensionless vertical
coordinate stretching function at gridpoint (k) with a range of
-1 <= C(k) <= 0, C(0) corresponds to eta(n,j,i) whereas
C(-1) corresponds to depth(j,i); and the constant depth_c,
(positive value), is a critical depth controlling the stretching.
</p>
<p>
The format for the formula_terms attribute is
</p>
<pre class="wiki">formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"
</pre><p>
<strong>Ocean s-coordinate, generic form 2</strong>
</p>
<pre class="wiki"> standard_name = "ocean_s_coordinate_g2"
</pre><blockquote>
<p>
Definition:
</p>
<pre class="wiki"> z(n,k,j,i) = eta(n,j,i) + (eta(n,j,i) + depth(j,i)) * S(k,j,i)
where S(k,j,i) = (depth_c * s(k) + depth(j,i) * C(k)) / (depth_c + depth(j,i))
</pre></blockquote>
<p>
and where z(n,k,j,i) is the height, positive upwards, relative to
ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i);
eta(n,j,i) is the height of the ocean surface, positive upwards,
relative to ocean datum at gridpoint (n,j,i); s(k) is the
dimensionless coordinate at vertical gridpoint (k) with a
range of -1 <= s(k) <= 0, s(0) corresponds to eta(n,j,i) whereas
s(-1) corresponds to depth(j,i); C(k) is the dimensionless vertical
coordinate stretching function at gridpoint (k) with a range of
-1 <= C(k) <= 0, C(0) corresponds to eta(n,j,i) whereas
C(-1) correspond to depth(j,i); and the constant depth_c,
(positive value) is a critical depth controlling the stretching.
</p>
<p>
The format for the formula_terms attribute is
</p>
<pre class="wiki">formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"
</pre><h2 id="a5.Benefits">5. Benefits</h2>
<blockquote>
<p>
The oceanographic community, especially those producing or consuming products from s coordinate models (e.g. variants and derivatives of the Regional Ocean Modeling System (ROMS)) would benefit from the addition of these two new dimensionless vertical coordinate specifications. These two new coordinates have been exercised in the Unidata Common Data Model and the Unidata NetCDF-Java Library for the last two years. It's time to add them officially to the CF Conventions.
</p>
</blockquote>
<h2 id="a6.StatusQuo">6. Status Quo</h2>
<blockquote>
<p>
The only option currently to store modern ROMS results as CF compliant would be to write the entire Z field as a 4D array.
</p>
</blockquote>
en-usCF Metadatahttps://cf-trac.llnl.gov/trac/chrome/site/cf_logo.png
https://cf-trac.llnl.gov/trac/ticket/93
Trac 1.0.12rsignellMon, 10 Sep 2012 15:23:58 GMT
https://cf-trac.llnl.gov/trac/ticket/93#comment:1
https://cf-trac.llnl.gov/trac/ticket/93#comment:1
<p>
Summary: There have been no comments on this proposal since I posted it one month ago, so there don't appear to be any issues.
</p>
<p>
The next step according to:
<a class="ext-link" href="http://cf-pcmdi.llnl.gov/governance/governance-rules"><span class="icon"></span>http://cf-pcmdi.llnl.gov/governance/governance-rules</a>
is to provide an example dataset and wait 3 more weeks. So here is an example dataset, and with links to visualization in the IDV (to prove that this specification is already working correctly in Unidata's NetCDF-Java and in the Unidata Integrated Data Viewer:
</p>
<p>
Example dataset: May be obtained via OPeNDAP or HTTPServer server download at this location:
<a class="ext-link" href="http://geoport.whoi.edu/thredds/catalog/examples/catalog.html?dataset=examples/coawst_g1.nc"><span class="icon"></span>http://geoport.whoi.edu/thredds/catalog/examples/catalog.html?dataset=examples/coawst_g1.nc</a>
(e.g. wget <a class="ext-link" href="http://geoport.whoi.edu/thredds/fileServer/examples/coawst_g1.nc"><span class="icon"></span>http://geoport.whoi.edu/thredds/fileServer/examples/coawst_g1.nc</a>)
</p>
<p>
Example 3D view of the temperature field from dataset above in Unidata's Integrated Data Viewer (<a class="ext-link" href="http://www.unidata.ucar.edu/software/idv/"><span class="icon"></span>http://www.unidata.ucar.edu/software/idv/</a>), showing that the new vertical coordinate specification is being correctly represented: <a class="ext-link" href="https://docs.google.com/open?id=0BzAHlPEEP_ujUE5zcG03VkVLY1k"><span class="icon"></span>https://docs.google.com/open?id=0BzAHlPEEP_ujUE5zcG03VkVLY1k</a>
</p>
<p>
If you want to test yourself, download the IDV, download the bundle URL below, and load this bundle in IDV:
<a class="ext-link" href="https://docs.google.com/open?id=0BzAHlPEEP_ujaDZnWGIwampJckU"><span class="icon"></span>https://docs.google.com/open?id=0BzAHlPEEP_ujaDZnWGIwampJckU</a>
This bundle accesses the OPeNDAP link, so you don't need to download the NetCDF file to visualize the data in IDV.
</p>
<ul><li>Rich Signell
</li></ul>
TicketjonathanTue, 11 Sep 2012 08:55:49 GMT
https://cf-trac.llnl.gov/trac/ticket/93#comment:2
https://cf-trac.llnl.gov/trac/ticket/93#comment:2
<p>
Dear Rich
</p>
<p>
Thanks for this proposal. It needs a moderator, and according to the rules it needs at least three people in favour of it. I'm happy to support it in principle, and it would be good to hear from others in support.
</p>
<p>
I have some comments, though. Apologies for being slow: I was on holiday. I don't follow the description of the formulae. By "s(0)" do you mean "s=0", and similarly for other conditions? It appears that s and C must be linked in some way; you get eta, for instance, by imposing conditions on both s and C. Would it be better, therefore, to state them as simultaneous conditions, rather than describing the conditions for s and C separately? Having said that, it have to admit that I may have misunderstood it completely. If s=0 and C=0 in the first case, for example, then S=0 and z=eta/depth, not eta. What have I done wrong? Or perhaps that is what is supposed to happen? If so, maybe you could start by saying that the resulting coordinate is a fraction of the local depth.
</p>
<p>
Thanks
</p>
<p>
Jonathan
</p>
TicketrsignellTue, 11 Sep 2012 13:49:34 GMT
https://cf-trac.llnl.gov/trac/ticket/93#comment:3
https://cf-trac.llnl.gov/trac/ticket/93#comment:3
<p>
Jonathan,
Yes, s(0) means "at s = 0", and s(-1) means "at s = -1". Both "s" and "C" are functions that have a valid_range [-1,0]. "s" has uniform spacing with values determined by the number of layers and the position of the variable within the layer. For example, if the model has 5 layers, the "w" vertical velocity component (and other variables located at the interfaces between the layers) will have a vertical coordinate "s" variable with values [-1.0 -0.8 -0.6 -0.4 -0.2 -0.0]. The "u" and "v" horizontal velocity components (and other variables located in the middle of the layers) will have a different "s" variable with values [-0.9 -0.7 -0.5 -0.3 -0.1]. The "C" function, meanwhile, is free to be any monotonic function with values in the range [-1.0 0], and is used to control the stretching (more resolution near the surface, near the bottom, etc). I have made a plot of these functions for the test file I provided at: <a class="ext-link" href="http://www.screencast.com/t/2nodlugvo"><span class="icon"></span>http://www.screencast.com/t/2nodlugvo</a>
</p>
<p>
Based on this information, can you suggest language for the CF conventions doc that would make this more clear to you (and others)?
</p>
<p>
-Rich
</p>
TicketrsignellWed, 12 Sep 2012 10:56:59 GMT
https://cf-trac.llnl.gov/trac/ticket/93#comment:4
https://cf-trac.llnl.gov/trac/ticket/93#comment:4
<p>
Jonathan,
You mentioned that I needed a moderator for this ticket. I have been playing the role of moderator for this ticket because it seems like the natural thing to do, and don't want to bug others to do a job that I feel I should be doing myself.
</p>
<p>
Reading the rules again at:
<a class="ext-link" href="http://cf-pcmdi.llnl.gov/governance/governance-rules"><span class="icon"></span>http://cf-pcmdi.llnl.gov/governance/governance-rules</a>
it doesn't seem to explicitly exclude the proposer from being the moderator as well. The important thing, it would seem is to reconcile the differences of opinion enough to get at least three folks to support for it, including at least two members of the conventions committee. Do you (or others) see this the same way, or do you feel it's important that the proposer be barred from the moderator role?
</p>
TicketrussWed, 12 Sep 2012 12:29:42 GMT
https://cf-trac.llnl.gov/trac/ticket/93#comment:5
https://cf-trac.llnl.gov/trac/ticket/93#comment:5
<p>
I support the proposal. If an alternate moderator is needed, I also volunteer to serve in that role.
</p>
TicketjonathanSun, 30 Sep 2012 08:16:15 GMT
https://cf-trac.llnl.gov/trac/ticket/93#comment:6
https://cf-trac.llnl.gov/trac/ticket/93#comment:6
<p>
Dear Rich
</p>
<p>
Thanks for your explanations. To avoid my initial misunderstandings, I would say:
</p>
<p>
where z(n,k,j,i) is the height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i); eta(n,j,i) is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint (n,j,i); depth(j,i) is the distance from ocean datum to sea floor (positive value) at gridpoint (j,i); s(k) is the dimensionless coordinate at vertical gridpoint (k); C(k) is the dimensionless vertical coordinate stretching function at gridpoint (k); and the constant depth_c, (positive value), is a critical depth controlling the stretching. s(k) and C(k) are both monotonic functions of k in the range -1 to 0; both s and C equal -1 at the sea floor, where z=depth, and both equal 0 at the sea surface, where z=eta. At intermediate depths their values are unrelated.
</p>
<p>
It's the same words in both cases, isn't it, but different formulae. The above isn't very different from what you said, and I hope it's correct.
</p>
<p>
This proposal also implies that two new standard_names are needed (for the two new types of s coordinate). I suggest it would be helpful to propose those to the email list, as otherwise they might not get picked up.
</p>
<p>
I note that the datum is not defined, and the same formulae might be applied to eta and depth wrt geoid or wrt mean sea level, for example. I suppose that is OK. The standard_names of the components would distinguish the datum, but it would depend on software that computed the dimensional coordinate using it in a way which was consistent with the datum.
</p>
<p>
Regarding moderators, that's probably a subject for a different ticket. You are right, the rules don't say that the proposer can't be the moderator, but I've always assumed it, as it seems good practice to me. It can be hard to be completely objective about one's own proposal. That is absolutely not a comment on your conduct of this ticket!
</p>
<p>
Best wishes
</p>
<p>
Jonathan
</p>
TicketrsignellMon, 01 Oct 2012 14:38:15 GMT
https://cf-trac.llnl.gov/trac/ticket/93#comment:7
https://cf-trac.llnl.gov/trac/ticket/93#comment:7
<p>
Jonathan,
As per your suggestion, I'll submit these vertical coordinate standard names "ocean_s_coordinate_g1" and "ocean_s_coordinate_g2" to the standard_name list. And your suggestioned rewording of the description is fine with me. So here is my modified proposal with rewording:
</p>
<p>
Proposed additions to:
<strong>Appendix D. Dimensionless Vertical Coordinates</strong>
</p>
<p>
<strong>Ocean s-coordinate, generic form 1</strong>
</p>
<pre class="wiki"> standard_name = "ocean_s_coordinate_g1"
</pre><p>
Definition:
</p>
<pre class="wiki"> z(n,k,j,i) = S(k,j,i) + eta(n,j,i) * (1 + S(k,j,i) / depth(j,i))
where S(k,j,i) = depth_c * s(k) + (depth(j,i) - depth_c) * C(k)
</pre><p>
and where z(n,k,j,i) is the height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i); eta(n,j,i) is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint (n,j,i); depth(j,i) is the distance from ocean datum to sea floor (positive value) at gridpoint (j,i); s(k) is the dimensionless coordinate at vertical gridpoint (k); C(k) is the dimensionless vertical coordinate stretching function at gridpoint (k); and the constant depth_c, (positive value), is a critical depth controlling the stretching. s(k) and C(k) are both monotonic functions of k in the range -1 to 0; both s and C equal -1 at the sea floor, where z=depth, and both equal 0 at the sea surface, where z=eta. At intermediate depths their values are unrelated.
</p>
<p>
The format for the formula_terms attribute is
</p>
<pre class="wiki">formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"
</pre><p>
<strong>Ocean s-coordinate, generic form 2</strong>
</p>
<pre class="wiki"> standard_name = "ocean_s_coordinate_g2"
</pre><p>
Definition:
</p>
<pre class="wiki"> z(n,k,j,i) = eta(n,j,i) + (eta(n,j,i) + depth(j,i)) * S(k,j,i)
where S(k,j,i) = (depth_c * s(k) + depth(j,i) * C(k)) / (depth_c + depth(j,i))
</pre><p>
and where z(n,k,j,i) is the height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i); eta(n,j,i) is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint (n,j,i); depth(j,i) is the distance from ocean datum to sea floor (positive value) at gridpoint (j,i); s(k) is the dimensionless coordinate at vertical gridpoint (k); C(k) is the dimensionless vertical coordinate stretching function at gridpoint (k); and the constant depth_c, (positive value), is a critical depth controlling the stretching. s(k) and C(k) are both monotonic functions of k in the range -1 to 0; both s and C equal -1 at the sea floor, where z=depth, and both equal 0 at the sea surface, where z=eta. At intermediate depths their values are unrelated.
</p>
<p>
The format for the formula_terms attribute is
</p>
<pre class="wiki">formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"
</pre>
TicketjonathanThu, 01 Nov 2012 09:05:57 GMT
https://cf-trac.llnl.gov/trac/ticket/93#comment:8
https://cf-trac.llnl.gov/trac/ticket/93#comment:8
<p>
Since Rich, Russ and I support this and no-one has commented for more than three weeks, I think we can conclude that this proposal is accepted (regardless of who is the moderator!). It should therefore be included in the next version of CF. Rich is already named as an author of CF. Thanks, Rich.
</p>
<p>
Jonathan
</p>
TicketmarkhTue, 08 Mar 2016 17:54:19 GMTstatus changed; resolution set
https://cf-trac.llnl.gov/trac/ticket/93#comment:9
https://cf-trac.llnl.gov/trac/ticket/93#comment:9
<ul>
<li><strong>status</strong>
changed from <em>new</em> to <em>closed</em>
</li>
<li><strong>resolution</strong>
set to <em>fixed</em>
</li>
</ul>
<p>
closed by
<a class="ext-link" href="https://github.com/cf-convention/cf-conventions/pull/62"><span class="icon"></span>https://github.com/cf-convention/cf-conventions/pull/62</a>
</p>
Ticket