Support for N axis dimensions mapped to N coordinates (#343)

docs/api.rst

@@ -22,11 +22,11 @@ Below is a list of top-level API functions available in ``xcdat``.
     open_dataset
     open_mfdataset
     center_times
-    decode_non_cf_time
+    decode_time
     swap_lon_axis
     compare_datasets
-    get_axis_coord
-    get_axis_dim
+    get_dim_coords
+    get_dim_keys
     create_gaussian_grid
     create_global_mean_grid
     create_grid
@@ -165,7 +165,7 @@ It is especially useful for those who are transitioning over from CDAT to xarray
      - ``Dataset.spatial.average("VAR_KEY", axis=["X", "Y"])`` specifying ``lat_bounds`` and ``lon_bounds``
      - ``cdutil.averager(TransientVariable, axis="xy")``, optionally subset ``TransientVariable`` with ``cdutil.region.domain()``
    * - Decode time coordinates with CF/Non-CF units?
-     - ``xr.decode_cf()`` specifying ``decode_times=True``, or ``xcdat.decode_non_cf_time()``
+     - ``xr.decode_cf()`` specifying ``decode_times=True``, or ``xcdat.decode_time()``
      - ``cdms2.axis.Axis.asComponentTime()``
    * - Temporally averaging with a single time-averaged snapshot and time coordinates removed?
      - ``Dataset.temporal.average("VAR_KEY")``

docs/examples/general-utilities.ipynb

@@ -4533,26 +4533,42 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "2ab105f4",
    "metadata": {},
    "source": [
-    "## Get an axis coordinate variable\n",
+    "## Get the dimension coordinates for an axis.\n",
     "\n",
-    "In `xarray`, you can get a coordinate variable by directly referencing its name (e.g., `ds.lat`).\n",
+    "In `xarray`, you can get a dimension coordinates by directly referencing its name (e.g., `ds.lat`). `xcdat` provides an alternative way to get dimension coordinates agnostically by simply passing the CF axis key to applicable APIs.\n",
     "\n",
-    "`xcdat` provides an alternative way to get coordinate variable agnostically by simply passing the name of the axis to the related API.\n",
+    "* Related API: [xcdat.get_dim_coords()](../generated/xcdat.get_dim_coords.rst)\n",
     "\n",
-    "* Related API: [xcdat.get_axis_coord()](../generated/xcdat.get_axis_coord.rst)\n",
+    "Helpful knowledge:\n",
     "\n",
-    "This API requires that either the `axis` attr or `standard_name` attr is set, or the name of the dimension follows the valid short-hand convention (e.g., 'lat' for latitude)."
+    "* This API uses ``cf_xarray`` to interpret CF axis names and coordinate names in the xarray object attributes. Refer to [Metadata Interpretation](../faqs.rst) for more information.\n",
+    "\n",
+    "Xarray documentation on coordinates ([source](https://docs.xarray.dev/en/stable/user-guide/data-structures.html#coordinates)):\n",
+    "\n",
+    "* There are two types of coordinates in xarray:\n",
+    "\n",
+    "  * **dimension coordinates** are one dimensional coordinates with a name equal to their sole dimension (marked by * when printing a dataset or data array). They are used for label based indexing and alignment, like the index found on a pandas DataFrame or Series. Indeed, these “dimension” coordinates use a pandas.Index internally to store their values.\n",
+    "\n",
+    "  * **non-dimension coordinates** are variables that contain coordinate data, but are not a dimension coordinate. They can be multidimensional (see Working with Multidimensional Coordinates), and there is no relationship between the name of a non-dimension coordinate and the name(s) of its dimension(s). Non-dimension coordinates can be useful for indexing or plotting; otherwise, xarray does not make any direct use of the values associated with them. They are not used for alignment or automatic indexing, nor are they required to match when doing arithmetic (see Coordinates).\n",
+    "\n",
+    "* Xarray’s terminology differs from the [CF terminology](https://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#terminology), where the “dimension coordinates” are called “coordinate variables”, and the “non-dimension coordinates” are called “auxiliary coordinate variables” (see [GH1295](https://github.com/pydata/xarray/issues/1295) for more details).\n",
+    "\n",
+    "\n",
+    "\n"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "15b5441d",
    "metadata": {},
    "source": [
+    "\n",
     "### 1. `axis` attr"
    ]
   },
@@ -4606,16 +4622,6 @@
     "ds.lat.attrs[\"standard_name\"]"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "3740761b",
-   "metadata": {},
-   "source": [
-    "### 3. Name of the dimension\n",
-    "\n",
-    "Must be the short name (e.g., \"lat\" for latitude and \"lon\" for longitude)"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": 22,
@@ -4637,14 +4643,6 @@
     "\"lat\" in ds.dims"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "b0591ecd",
-   "metadata": {},
-   "source": [
-    "Requires at least at one of the three keys above to be set."
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": 24,
@@ -5107,7 +5105,7 @@
     }
    ],
    "source": [
-    "xcdat.get_coord_var(ds, axis=\"Y\")"
+    "xcdat.get_axis_coord(ds, axis=\"Y\")"
    ]
   }
  ],