From 0824df2aca3036b6b521cc5bb714d0b449eceb50 Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Mon, 24 Jun 2024 20:18:24 -0600 Subject: [PATCH] Docs cleanup (#518) * Docs cleanup * More links --- doc/bounds.md | 5 +++-- doc/dsg.md | 5 +++++ doc/flags.md | 4 ++++ doc/geometry.md | 2 +- doc/grid_mappings.md | 7 ++++--- doc/parametricz.md | 6 ++++++ doc/selecting.md | 10 +++++++++- doc/sgrid_ugrid.md | 5 +++++ doc/units.md | 6 +++++- 9 files changed, 42 insertions(+), 8 deletions(-) diff --git a/doc/bounds.md b/doc/bounds.md index 537aef7e..21d85fcd 100644 --- a/doc/bounds.md +++ b/doc/bounds.md @@ -4,12 +4,13 @@ # Bounds Variables -See - +```{seealso} +1. [CF conventions on coordinate bounds](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#cell-boundaries) 1. {py:attr}`Dataset.cf.bounds`, 1. {py:func}`Dataset.cf.add_bounds`, 1. {py:func}`cf_xarray.bounds_to_vertices`, 1. {py:func}`cf_xarray.vertices_to_bounds` +``` `cf_xarray` supports parsing [coordinate bounds](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#cell-boundaries) as encoded in the CF `bounds` attribute. A useful feature for incomplete dataset is also the automatic bounds estimation possible through `cf.add_bounds`. This method will estimate the missing bounds by finding the middle points between elements of the given coordinate, but also by extrapolating to find the outer bounds of the grid. This linear estimation works well with rectilinear grids, but it is only a coarse approximation for curvilinear and simple irregular grids. diff --git a/doc/dsg.md b/doc/dsg.md index 936480e8..c90e6fdc 100644 --- a/doc/dsg.md +++ b/doc/dsg.md @@ -23,6 +23,11 @@ xr.set_options(display_expand_data=False) # Discrete Sampling Geometries +```{seealso} +1. [CF conventions on Discrete Sampling Geometries](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#discrete-sampling-geometries) +1. {py:attr}`Dataset.cf.cf_roles` +``` + `cf_xarray` supports identifying variables by the [`cf_role` attribute](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#discrete-sampling-geometries). ```{code-cell} diff --git a/doc/flags.md b/doc/flags.md index 448cc99a..5e37df36 100644 --- a/doc/flags.md +++ b/doc/flags.md @@ -15,6 +15,10 @@ kernelspec: # Flag Variables +```{seealso} +1. [CF conventions on flag variables and masks](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#flags) +``` + `cf_xarray` has some support for [flag variables](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#flags), including flag masks. ## Flag Values diff --git a/doc/geometry.md b/doc/geometry.md index 21640aa7..9ea702eb 100644 --- a/doc/geometry.md +++ b/doc/geometry.md @@ -88,7 +88,7 @@ cfxr.cf_to_shapely(ds_cf) ``` This conversion adds coordinates that aren't in the `xr.DataArray` that we started with. -By default these are called `crd_x` and `crd_y` unless `grid_mapping` is specified. +By default these are called `'crd_x'` and `'crd_y'` unless `grid_mapping` is specified. ## Gotchas diff --git a/doc/grid_mappings.md b/doc/grid_mappings.md index a653f6cc..15e48379 100644 --- a/doc/grid_mappings.md +++ b/doc/grid_mappings.md @@ -13,10 +13,11 @@ kernelspec: # Grid Mappings -See - -1. {py:attr}`Dataset.cf.grid_mapping_names`, +```{seealso} +1. [CF conventions on grid mappings and projections](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#grid-mappings-and-projections) +1. {py:attr}`Dataset.cf.grid_mapping_names` 1. {py:attr}`DataArray.cf.grid_mapping_name` +``` `cf_xarray` understands the concept of coordinate projections using the [grid_mapping](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#grid-mappings-and-projections) attribute convention. For example, the dataset might contain two sets of coordinates: diff --git a/doc/parametricz.md b/doc/parametricz.md index d1115552..77f67924 100644 --- a/doc/parametricz.md +++ b/doc/parametricz.md @@ -22,6 +22,12 @@ xr.set_options(display_expand_data=False) # Parametric Vertical Coordinates +```{seealso} +1. [CF conventions on parametric vertical coordinates](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#parametric-vertical-coordinate) +2. {py:meth}`Dataset.cf.decode_vertical_coords` +3. {py:attr}`Dataset.cf.formula_terms` +``` + `cf_xarray` supports decoding [parametric vertical coordinates](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#parametric-vertical-coordinate) encoded in the `formula_terms` attribute using {py:meth}`Dataset.cf.decode_vertical_coords`. Right now, only the two ocean s-coordinates and `ocean_sigma_coordinate` are supported, but support for the [rest](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#parametric-v-coord) should be easy to add (Pull Requests are very welcome!). ## Decoding parametric coordinates diff --git a/doc/selecting.md b/doc/selecting.md index 93bd596f..0a06e25f 100644 --- a/doc/selecting.md +++ b/doc/selecting.md @@ -22,7 +22,15 @@ xr.set_options(display_expand_data=False) # Selecting DataArrays -A second powerful feature of `cf_xarray` is the ability select DataArrays using special "CF names" like the "latitude", or "longitude" coordinate names, "X" or "Y" axes names, oreven using the `standard_name` attribute if present. +```{seealso} +CF conventions on +1. [coordinate variables](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#coordinate-types) +1. [cell bounds and measures](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#_data_representative_of_cells) +1. [standard name](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#standard-name) +1. [ancillary data](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#ancillary-data) +``` + +A powerful feature of `cf_xarray` is the ability select DataArrays using special "CF names" like the "latitude", or "longitude" coordinate names, "X" or "Y" axes names, oreven using the `standard_name` attribute if present. To demonstrate this, let's load a few datasets diff --git a/doc/sgrid_ugrid.md b/doc/sgrid_ugrid.md index 62b4da57..6e840048 100644 --- a/doc/sgrid_ugrid.md +++ b/doc/sgrid_ugrid.md @@ -9,6 +9,11 @@ kernelspec: # SGRID / UGRID +```{seealso} +1. [SGRID conventions](https://sgrid.github.io/sgrid/) +1. [UGRID conventions](http://ugrid-conventions.github.io/ugrid-conventions/) +``` + ## SGRID `cf_xarray` can parse the attributes on the `grid_topology` variable to identify dimension names with axes names `X`, `Y`, `Z`. diff --git a/doc/units.md b/doc/units.md index 8dd07afd..4b743358 100644 --- a/doc/units.md +++ b/doc/units.md @@ -10,9 +10,13 @@ hide-toc: true # Units +```{seealso} +1. [CF conventions on units](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units) +``` + The xarray ecosystem supports unit-aware arrays using [pint](https://pint.readthedocs.io) and [pint-xarray](https://pint-xarray.readthedocs.io). Some changes are required to make these packages work well with [UDUNITS format recommended by the CF conventions](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units). -`cf_xarray` makes those recommended changes when you `import cf_xarray.units`. These changes allow pint to parse and format UDUNIT units strings, and add several custom units like `degrees_north`, `psu` etc. +`cf_xarray` makes those recommended changes when you `import cf_xarray.units`. These changes allow pint to parse and format UDUNIT units strings, and add several custom units like `degrees_north` for latitude, `psu` for ocean salinity, etc. ## Formatting units