More doc updates (#281)

Author: dcherian

cf_xarray/accessor.py

@@ -232,11 +232,6 @@ def _get_axis_coord(obj: Union[DataArray, Dataset], key: str) -> List[str]:
         DataArray belonging to the coordinate to be checked
     key : str, ["X", "Y", "Z", "T", "longitude", "latitude", "vertical", "time"]
         key to check for.
-    error : bool
-        raise errors when key is not found or interpretable. Use False and provide default
-        to replicate dict.get(k, None).
-    default : Any
-        default value to return when error is False.
 
     Returns
     -------
@@ -1011,7 +1006,6 @@ def isin(self, test_elements):
             to the corresponding value in "flag_values" before passing
             that on to DataArray.isin.
 
-
         Returns
         -------
         isin : DataArray
@@ -1409,11 +1403,6 @@ def standard_names(self) -> Dict[str, List[str]]:
         """
         Returns a dictionary mapping standard names to variable names.
 
-        Parameters
-        ----------
-        obj : DataArray, Dataset
-            Xarray object to process
-
         Returns
         -------
         Dictionary mapping standard names to variable names.
@@ -1446,12 +1435,13 @@ def get_associated_variable_names(
         ----------
         name : Hashable
         skip_bounds : bool, optional
-        error: bool, optional
+        error : bool, optional
             Raise or ignore errors.
 
         Returns
-        ------
-        Dict with keys "ancillary_variables", "cell_measures", "coordinates", "bounds"
+        -------
+        names : dict
+            Dictionary with keys "ancillary_variables", "cell_measures", "coordinates", "bounds"
         """
         keys = ["ancillary_variables", "cell_measures", "coordinates", "bounds"]
         coords: Dict[str, List[str]] = {k: [] for k in keys}
@@ -1542,7 +1532,7 @@ def rename_like(
         ----------
         other : DataArray, Dataset
             Variables will be renamed to match variable names in this xarray object
-        skip: str, Iterable[str], optional
+        skip : str, Iterable[str], optional
             Limit the renaming excluding
             ("axes", "bounds", cell_measures", "coordinates", "standard_names")
             or a subset thereof.
@@ -1706,7 +1696,7 @@ def differentiate(
 
         Parameters
         ----------
-        positive_upward: optional, bool
+        positive_upward : optional, bool
             Change sign of the derivative based on the ``"positive"`` attribute of ``coord``
             so that positive values indicate increasing upward.
             If ``positive=="down"``, then multiplied by -1.
@@ -1719,8 +1709,8 @@ def differentiate(
         --------
         DataArray.cf.differentiate
         Dataset.cf.differentiate
-        xarray.DataArray.differentiate: underlying xarray function
-        xarray.Dataset.differentiate: underlying xarray function
+        xarray.DataArray.differentiate : underlying xarray function
+        xarray.Dataset.differentiate : underlying xarray function
         """
         coord = apply_mapper(
             (_single(_get_coords),), self._obj, coord, error=False, default=[coord]
@@ -1755,13 +1745,13 @@ def add_canonical_attributes(
 
         Parameters
         ----------
-        override: bool
+        override : bool
             Override existing attributes.
-        skip: str, iterable, optional
+        skip : str, iterable, optional
             Attribute(s) to skip: ``{"units", "grib", "amip", "description"}``.
-        verbose: bool
+        verbose : bool
             Print added attributes to screen.
-        source: optional
+        source : optional
             Path of `cf-standard-name-table.xml` or file object containing XML data.
             If ``None``, use the default version associated with ``cf-xarray``.
 

cf_xarray/geometry.py

@@ -19,18 +19,18 @@ def reshape_unique_geometries(
     Parameters
     ----------
     ds : xr.Dataset
-      A Dataset.
+        A Dataset.
     geom_var : string
-      Name of the variable in `ds` that contains the geometry objects of type shapely.geometry.
-      The variable must be 1D.
+        Name of the variable in `ds` that contains the geometry objects of type shapely.geometry.
+        The variable must be 1D.
     new_dim : string
-      Name of the new dimension in the returned object.
+        Name of the new dimension in the returned object.
 
     Returns
     -------
     Dataset
-      All variables sharing the dimension of `ds[geom_var]` are reshaped so that `new_dim`
-      as a length equal to the number of unique geometries.
+        All variables sharing the dimension of `ds[geom_var]` are reshaped so that `new_dim`
+        as a length equal to the number of unique geometries.
     """
     if ds[geom_var].ndim > 1:
         raise ValueError(
@@ -78,24 +78,25 @@ def shapely_to_cf(geometries: Union[xr.DataArray, Sequence], grid_mapping: str =
     Parameters
     ----------
     geometries : sequence of shapely geometries or xarray.DataArray
-      A sequence of geometry objects or a Dataset with a "geometry" variable storing such geometries.
-      All geometries must be of the same base type : Point, Line or Polygon, but multipart geometries are accepted.
+        A sequence of geometry objects or a Dataset with a "geometry" variable storing such geometries.
+        All geometries must be of the same base type : Point, Line or Polygon, but multipart geometries are accepted.
+
     grid_mapping : str, optional
-      A CF grid mapping name. When given, coordinates and attributes are named and set accordingly.
-      Defaults to None, in which case the coordinates are simply names "crd_x" and "crd_y".
+        A CF grid mapping name. When given, coordinates and attributes are named and set accordingly.
+        Defaults to None, in which case the coordinates are simply names "crd_x" and "crd_y".
 
-      .. warning::
-          Only the `longitude_latitude` grid mapping is currently implemented.
+        .. warning::
+            Only the `longitude_latitude` grid mapping is currently implemented.
 
     Returns
     -------
     xr.Dataset
-      A dataset with shapely geometry objects translated into CF-compliant variables :
-       - 'x', 'y' : the node coordinates
-       - 'crd_x', 'crd_y' : the feature coordinates (might have different names if `grid_mapping` is available).
-       - 'node_count' : The number of nodes per feature. Absent if all instances are Points.
-       - 'geometry_container' : Empty variable with attributes describing the geometry type.
-       - Other variables are not implemented as only Points are currently understood.
+        A dataset with shapely geometry objects translated into CF-compliant variables :
+         - 'x', 'y' : the node coordinates
+         - 'crd_x', 'crd_y' : the feature coordinates (might have different names if `grid_mapping` is available).
+         - 'node_count' : The number of nodes per feature. Absent if all instances are Points.
+         - 'geometry_container' : Empty variable with attributes describing the geometry type.
+         - Other variables are not implemented as only Points are currently understood.
     """
     # Get all types to call the appropriate translation function.
     types = {
@@ -139,15 +140,15 @@ def cf_to_shapely(ds: xr.Dataset):
     Parameters
     ----------
     ds : xr.Dataset
-      Must contain a `geometry_container` variable with attributes giving the geometry specifications.
-      Must contain all variables needed to reconstruct the geometries listed in these specifications.
+        Must contain a ``geometry_container`` variable with attributes giving the geometry specifications.
+        Must contain all variables needed to reconstruct the geometries listed in these specifications.
 
     Returns
     -------
-    xr.DataArray
-      A 1D DataArray of shapely objects.
-      It has the same dimension as the `node_count` or the coordinates variables, or
-      'features' if those were not present in `ds `.
+    da: xr.DataArray
+        A 1D DataArray of shapely objects.
+        It has the same dimension as the ``node_count`` or the coordinates variables, or
+        ``features`` if those were not present in ``ds``.
     """
     geom_type = ds.geometry_container.attrs["geometry_type"]
     if geom_type == "point":
@@ -168,13 +169,13 @@ def points_to_cf(pts: Union[xr.DataArray, Sequence]):
     Parameters
     ----------
     pts : sequence of shapely.geometry.Point or MultiPoint
-      The sequence of [multi]points to translate to a CF dataset.
+        The sequence of [multi]points to translate to a CF dataset.
 
     Returns
     -------
     xr.Dataset
-      A Dataset with variables 'x', 'y', 'crd_x', 'crd_y', 'node_count' and 'geometry_container'.
-      The coordinates of MultiPoint instances are their first point.
+        A Dataset with variables 'x', 'y', 'crd_x', 'crd_y', 'node_count' and 'geometry_container'.
+        The coordinates of MultiPoint instances are their first point.
     """
     if isinstance(pts, xr.DataArray):
         dim = pts.dims[0]
@@ -229,16 +230,16 @@ def cf_to_points(ds: xr.Dataset):
     Parameters
     ----------
     ds : xr.Dataset
-      A dataset with CF-compliant point geometries.
-      Must have a "geometry_container" variable with at least a 'node_coordinates' attribute.
-      Must also have the two 1D variables listed by this attribute.
+        A dataset with CF-compliant point geometries.
+        Must have a "geometry_container" variable with at least a 'node_coordinates' attribute.
+        Must also have the two 1D variables listed by this attribute.
 
     Returns
     -------
     geometry : xr.DataArray
-      A 1D array of shapely.geometry.[Multi]Point objects.
-      It has the same dimension as the `node_count` or the coordinates variables, or
-      'features' if those were not present in `ds `.
+        A 1D array of shapely.geometry.[Multi]Point objects.
+        It has the same dimension as the ``node_count`` or the coordinates variables, or
+        ``'features'`` if those were not present in ``ds``.
     """
     from shapely.geometry import MultiPoint, Point
 

cf_xarray/options.py

@@ -14,19 +14,29 @@
 
 class set_options:
     """Set options for cf-xarray in a controlled context.
-    Currently supported options:
-    - ``custom_critera``: Translate from axis, coord, or custom name to
-      variable name optionally  using ``custom_criteria``. Default: [].
+
+    Parameters
+    ----------
+    custom_criteria : dict
+        Translate from axis, coord, or custom name to
+        variable name optionally using ``custom_criteria``. Default: [].
+
+    Examples
+    --------
 
     You can use ``set_options`` either as a context manager:
+
+    >>> import numpy as np
+    >>> import xarray as xr
     >>> my_custom_criteria = { 'ssh': {'name': 'elev$'} }
     >>> ds = xr.Dataset({"elev": np.arange(1000)})
     >>> with cf_xarray.set_options(custom_criteria=my_custom_criteria):
-    ...     assert (ds['elev'] == ds.cf['ssh']).all()
+    ...     xr.testing.assert_identical(ds['elev'], ds.cf['ssh'])
 
     Or to set global options:
+
     >>> cf_xarray.set_options(custom_criteria=my_custom_criteria)
-    >>> assert (ds['elev'] == ds.cf['ssh']).all()
+    >>> xr.testing.assert_identical(ds['elev'], ds.cf['ssh'])
     """
 
     def __init__(self, **kwargs):

ci/doc.yml

@@ -9,7 +9,7 @@ dependencies:
   - pooch
   - xarray
   - sphinx
-  - nbsphinx
+  - sphinx-copybutton
   - numpydoc
   - sphinx-autosummary-accessors
   - ipython

doc/api.rst

@@ -13,6 +13,7 @@ Top-level API
     vertices_to_bounds
     shapely_to_cf
     cf_to_shapely
+    set_options
 
 .. currentmodule:: xarray
 

doc/conf.py

@@ -50,6 +50,7 @@
     "sphinx_autosummary_accessors",
     "IPython.sphinxext.ipython_directive",
     "myst_nb",
+    "sphinx_copybutton",
 ]
 
 extlinks = {
@@ -252,7 +253,7 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "xarray": ("http://xarray.pydata.org/en/stable/", None),
+    "xarray": ("https://xarray.pydata.org/en/stable/", None),
 }
 
 autosummary_generate = True

doc/custom-criteria.md

@@ -1,14 +1,88 @@
 ---
 jupytext:
   text_representation:
-    format_name: myst    
+    format_name: myst
 kernelspec:
   display_name: Python 3
   name: python3
 ---
 ```{eval-rst}
-.. currentmodule:: xarray
+.. currentmodule:: cf_xarray
 ```
 
 (custom_criteria)=
 # Custom Criteria
+
+Fundamentally, cf_xarray uses rules or "criteria" to interpret user input using the
+attributes of an Xarray object (`.attrs`). These criteria are simple dictionaries. For example, here are the criteria used for identifying a "latitude" variable:
+```python
+coordinate_criteria = {
+    "latitude": {
+        "standard_name": ("latitude",),
+        "units": (
+            "degree_north",
+            "degree_N",
+            "degreeN",
+            "degrees_north",
+            "degrees_N",
+            "degreesN",
+        ),
+        "_CoordinateAxisType": ("Lat",),
+    },
+}
+```
+
+This dictionary maps the user input (`"latitude"`) to another dictionary which in turn maps an attribute name to a tuple of acceptable values for that attribute. So any variable with either `standard_name: latitude` or `_CoordinateAxisType: Lat_` or any of the `unit`s listed above will match the user-input `"latitude"`.
+
+cf_xarray lets you provide your own custom criteria in addition to those built-in. Here's an example:
+```{code-cell}
+import cf_xarray as cfxr
+import numpy as np
+import xarray as xr
+
+ds = xr.Dataset({
+    "salt1": ("x", np.arange(10), {"standard_name": "sea_water_salinity"}),
+    "salt2": ("x", np.arange(10), {"standard_name": "sea_water_practical_salinity"}),
+})
+
+# first define our criteria
+salt_criteria = {
+    "sea_water_salinity": {
+        "standard_name": "sea_water_salinity|sea_water_practical_salinity"
+        }
+}
+```
+
+Now we apply our custom criteria temporarily using {py:func}`set_options` as a context manager. The following sets `"sea_water_salinity"` as an alias for variables that have either `"sea_water_salinity"` or `"sea_water_practical_salinity"` (note the use of regular expressions as a value). Here's how that works in practice
+```{code-cell}
+with cfxr.set_options(custom_criteria=salt_criteria):
+    salty = ds.cf[["sea_water_salinity"]]
+salty
+```
+
+Note that `salty` contains both `salt1` and `salt2`. Without setting these criteria, we  would only get `salt1` by default
+```{code-cell}
+ds.cf[["sea_water_salinity"]]
+```
+
+We can also use {py:func}`set_options` to set the criteria globally.
+```{code-cell}
+cfxr.set_options(custom_criteria=salt_criteria)
+ds.cf[["sea_water_salinity"]]
+```
+
+Again we get back both `salt1` and `salt2`. To limit side effects of setting criteria globally, we recommend that you use `set_options` as a context manager. 
+
+```{tip}
+To reset your custom criteria use `cfxr.set_options(custom_criteria=())`
+```
+
+You can also match on the variable name, though be careful!
+```{code-cell}
+salt_criteria = {
+    "salinity": {"name": "salt*"}
+}
+cfxr.set_options(custom_criteria=salt_criteria)
+
+ds.cf[["salinity"]]
+```

doc/flags.md

@@ -44,7 +44,7 @@ Similarly with membership tests using {py:meth}`DataArray.cf.isin`
 da.cf.isin(["indian_ocean", "pacific_ocean"])
 ```
 
-You can also check whether a DataArray has the appropriate attributes to be recognized as a flag variable.
+You can also check whether a DataArray has the appropriate attributes to be recognized as a flag variable using {py:meth}`DataArray.cf.is_flag_variable`
 ```{code-cell}
 da.cf.is_flag_variable
 ```

doc/units.md

@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    format_name: myst    
+    format_name: myst
 kernelspec:
   display_name: Python 3
   name: python3