Update usage.rst

[rabernat]

This update to the doc should resolve the confusion discussed in #251.

[AaronDavidSchneider]

Just to be complete you could add a word about atmospheres, what do you think @rabernat ?

[AaronDavidSchneider]

Hi, sorry to bother again. But the atmospheric Z in MITgcm is pressure, which decreases with altitude. So it's the same as for the ocean? Or am I wrong?

[rabernat]

Hi, sorry to bother again. But the atmospheric Z in MITgcm is pressure, which decreases with altitude. So it's the same as for the ocean? Or am I wrong?

You are right! But even when using pressure coordinates, we would still say that the surface is a "lower" level than 500mb. So the confusion is not as acute.

[ifenty]

@rabernat good doc description update.

FYIW, here is the new metadata attributes for k_, Z_ that I will use (in dictionary format):

Zl_attrs = {'long_name': "depth of the top face of tracer grid cells", 'units': 'm', 'positive': 'up', 'comment': "First element is 0m, the depth of the top face of the first tracer grid cell (ocean surface). Last element is the depth of the top face of the deepest grid cell. The use of 'l' in the variable name follows the MITgcm convention for ocean variables in which the lower (l) face of a tracer grid cell on the logical grid corresponds to the top face of the grid cell on the physical grid. In other words, the logical vertical grid of MITgcm ocean variables is inverted relative to the physical vertical grid.", 'coverage_content_type': 'coordinate', 'standard_name': 'depth'}

Zu_attrs = {'long_name': "depth of the bottom face of tracer grid cells", 'units': 'm', 'positive': 'up', 'comment': "First element is -10m, the depth of the bottom face of the first tracer grid cell. Last element is the depth of the bottom face of the deepest grid cell. The use of 'u' in the variable name follows the MITgcm convention for ocean variables in which the upper (u) face of a tracer grid cell on the logical grid corresponds to the bottom face of the grid cell on the physical grid. In other words, the logical vertical grid of MITgcm ocean variables is inverted relative to the physical vertical grid.", 'coverage_content_type': 'coordinate', 'standard_name': 'depth'}

k_l_attrs = {'axis': 'Z', 'long_name': "grid index in z corresponding to the top face of tracer grid cells ('w' locations)", 'c_grid_axis_shift': -0.5, 'swap_dim': 'Zl', 'comment': "First index corresponds to the top surface of the uppermost tracer grid cell. The use of 'l' in the variable name follows the MITgcm convention for ocean variables in which the lower (l) face of a tracer grid cell on the logical grid corresponds to the top face of the grid cell on the physical grid.", 'coverage_content_type': 'coordinate'}

k_u_attrs = {'axis': 'Z', 'long_name': "grid index in z corresponding to the bottom face of tracer grid cells ('w' locations)", 'c_grid_axis_shift': 0.5, 'swap_dim': 'Zu', 'comment': "First index corresponds to the bottom surface of the uppermost tracer grid cell. The use of 'u' in the variable name follows the MITgcm convention for ocean variables in which the upper (u) face of a tracer grid cell on the logical grid corresponds to the bottom face of the grid cell on the physical grid.", 'coverage_content_type': 'coordinate'}

[rabernat]

@ifenty - Is there any reason for us to be using distinct databases here? It's just more work to maintain, and more potential problems if things get out of sync.

Could we just put your dict into xmitgcm, and then you import it?

[ifenty]

@ifenty - Is there any reason for us to be using distinct databases here? It's just more work to maintain, and more potential problems if things get out of sync.

Could we just put your dict into xmitgcm, and then you import it?

I put together json metadata databases for all variables and coordinates (with input from ecco community). They are currently on GitHub (link to follow). If these were used in xmitgcm I would be delighted! It would certainly help users understand what these variables are, being more descriptive and I hope accurate than what is provided in the diagnostics package / "available diagnostics".

The main issue with me importing these dictionaries from xmitgcm for ecco is that we're under tighter constraints with respect to the standard_name field. PO.DAAC has generously agreed to host ECCO products and their guidelines require only official CF standard_names (no made up correctish sounding standard_names). Currently xmitgcm's database has these off-the-books standard_names. The fields "long_name" and "comments" are not constrained.

If xmitgcm is willing to do adopt the same guidelines as PODAAC with respect to only official CF standard_name (and units), then I'd be happy to have our databases "live" at xmitgcm.

What do you think?

[rabernat]

👍 to updating xmitgcm metadata to use CF standard names!

The only place we might get in trouble is with atmospheric simulations...

[ifenty]

@rabernat https://github.com/ECCO-GROUP/ECCO-ACCESS/tree/master/metadata/ECCOv4r4_metadata_json

Extract from ECCOv4r4_coordinate_metadata_for_native_datasets.json

   {
      "name": "XC",
      "standard_name": "longitude",
      "long_name": "longitude of tracer grid cell center",
      "comment": "nonuniform grid spacing",
      "units": "degrees_east",
      "bounds": "XC_bnds",
      "grid_dimension": "2D 3D",
      "coverage_content_type": "coordinate"
   },
   {
      "name": "YC",
      "standard_name": "latitude",
      "long_name": "latitude of tracer grid cell center",
      "units": "degrees_north",
      "comment": "nonuniform grid spacing",
      "bounds": "YC_bnds",
      "grid_dimension": "2D 3D",
      "coverage_content_type": "coordinate"
   },

[ifenty]

Hi, sorry to bother again. But the atmospheric Z in MITgcm is pressure, which decreases with altitude. So it's the same as for the ocean? Or am I wrong?

vertical levels in the ocean are depth (at least in every configuration I've ever used)

[rabernat]

I'm going to merge this for now. It's an incremental improvement in the docs. We can open a new issue to track the idea of using a shared metadata database between projects.