Skip to content

Commit

Permalink
Fix climo notebook missing T bounds and add notebook env setup in all…
Browse files Browse the repository at this point in the history 
… example notebooks (#623)
  • Loading branch information
@tomvothecoder
tomvothecoder authored Mar 18, 2024
1 parent b83a132 commit d0e33aa
Show file tree
Hide file tree
Showing 7 changed files with 1,376 additions and 940 deletions.
1,693 changes: 1,020 additions & 673 deletions docs/examples/climatology-and-departures.ipynb
View file

Large diffs are not rendered by default.

82 changes: 48 additions & 34 deletions docs/examples/general-utilities.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,10 @@
"\n",
"Authors:\n",
"\n",
"* [Tom Vo](https://github.com/tomvothecoder/)\n",
"* [Stephen Po-Chedley](https://github.com/pochedls/)\n",
"- [Tom Vo](https://github.com/tomvothecoder/)\n",
"- [Stephen Po-Chedley](https://github.com/pochedls/)\n",
"\n",
"\n",
"Date: 05/26/22"
"Date: 05/26/22\n"
]
},
{
Expand All @@ -25,7 +24,26 @@
"\n",
"This notebook demonstrates the use of general utility methods available in `xcdat`, including\n",
"the reorientation of the longitude axis, centering of time coordinates using time bounds, and\n",
"adding and getting bounds."
"adding and getting bounds.\n"
]
},
{
"cell_type": "markdown",
"id": "b8443fe9",
"metadata": {},
"source": [
"## Notebook Setup\n",
"\n",
"Create an Anaconda environment for this notebook using the command below, then select the\n",
"kernel in Jupyter.\n",
"\n",
"```bash\n",
"conda create -n xcdat_notebook -c conda-forge python xarray netcdf4 xcdat xesmf matplotlib nc-time-axis jupyter\n",
"```\n",
"\n",
"- `xesmf` is required for horizontal regridding with xESMF\n",
"- `matplotlib` is an optional dependency required for plotting with xarray\n",
"- `nc-time-axis` is an optional dependency required for `matplotlib` to plot `cftime` coordinates\n"
]
},
{
Expand All @@ -49,8 +67,8 @@
"\n",
"Related APIs:\n",
"\n",
"* [xcdat.open_dataset()](../generated/xcdat.open_dataset.rst)\n",
"* [xcdat.open_mfdataset()](../generated/xcdat.open_mfdataset.rst)"
"- [xcdat.open_dataset()](../generated/xcdat.open_dataset.rst)\n",
"- [xcdat.open_mfdataset()](../generated/xcdat.open_mfdataset.rst)\n"
]
},
{
Expand Down Expand Up @@ -906,10 +924,10 @@
"source": [
"## Reorient the longitude axis\n",
"\n",
"Longitude can be represented from 0 to 360 E or as 180 W to 180 E. ``xcdat`` allows you to convert between these axes systems.\n",
"Longitude can be represented from 0 to 360 E or as 180 W to 180 E. `xcdat` allows you to convert between these axes systems.\n",
"\n",
"* Related API: [xcdat.swap_lon_axis()](../generated/xcdat.swap_lon_axis.rst)\n",
"* Alternative solution: ``xcdat.open_mfdataset(dataset_links, lon_orient=(-180, 180))``\n"
"- Related API: [xcdat.swap_lon_axis()](../generated/xcdat.swap_lon_axis.rst)\n",
"- Alternative solution: `xcdat.open_mfdataset(dataset_links, lon_orient=(-180, 180))`\n"
]
},
{
Expand Down Expand Up @@ -1723,18 +1741,18 @@
"source": [
"## Center the time coordinates\n",
"\n",
"A given point of time often represents some time period (e.g., a monthly average). In this situation, data providers sometimes record the time as the beginning, middle, or end of the period. ``center_times()`` places the time coordinate in the center of the time interval (using time bounds to determine the center of the period).\n",
"A given point of time often represents some time period (e.g., a monthly average). In this situation, data providers sometimes record the time as the beginning, middle, or end of the period. `center_times()` places the time coordinate in the center of the time interval (using time bounds to determine the center of the period).\n",
"\n",
"* Related API: [xcdat.center_times()](../generated/xcdat.center_times.rst)\n",
"* Alternative solution: ``xcdat.open_mfdataset(dataset_links, center_times=True)``"
"- Related API: [xcdat.center_times()](../generated/xcdat.center_times.rst)\n",
"- Alternative solution: `xcdat.open_mfdataset(dataset_links, center_times=True)`\n"
]
},
{
"cell_type": "markdown",
"id": "b6ae5740",
"metadata": {},
"source": [
"The time bounds used for centering time coordinates:"
"The time bounds used for centering time coordinates:\n"
]
},
{
Expand Down Expand Up @@ -1777,7 +1795,7 @@
"id": "bcf8a44d",
"metadata": {},
"source": [
"Before centering time coordinates:"
"Before centering time coordinates:\n"
]
},
{
Expand Down Expand Up @@ -2208,7 +2226,7 @@
"id": "66db7abf",
"metadata": {},
"source": [
"After centering time coordinates:"
"After centering time coordinates:\n"
]
},
{
Expand Down Expand Up @@ -2635,11 +2653,11 @@
"source": [
"## Add bounds\n",
"\n",
"Bounds are critical to many ``xcdat`` operations. For example, they are used in determining the weights in spatial or temporal averages and in regridding operations. ``add_bounds()`` will attempt to produce bounds if they do not exist in the original dataset.\n",
"Bounds are critical to many `xcdat` operations. For example, they are used in determining the weights in spatial or temporal averages and in regridding operations. `add_bounds()` will attempt to produce bounds if they do not exist in the original dataset.\n",
"\n",
"* Related API: [xarray.Dataset.bounds.add_bounds()](../generated/xarray.Dataset.bounds.add_bounds.rst)\n",
"* Alternative solution: ``xcdat.open_mfdataset(dataset_links, add_bounds=True)``\n",
" * (Assuming the file doesn't already have bounds for your desired axis/axes)"
"- Related API: [xarray.Dataset.bounds.add_bounds()](../generated/xarray.Dataset.bounds.add_bounds.rst)\n",
"- Alternative solution: `xcdat.open_mfdataset(dataset_links, add_bounds=True)`\n",
" - (Assuming the file doesn't already have bounds for your desired axis/axes)\n"
]
},
{
Expand Down Expand Up @@ -2681,7 +2699,7 @@
"metadata": {},
"outputs": [],
"source": [
"# A `width` kwarg can be specified, which is width of the bounds relative to \n",
"# A `width` kwarg can be specified, which is width of the bounds relative to\n",
"# the position of the nearest points. The default value is 0.5.\n",
"ds4 = ds4.bounds.add_bounds(\"T\", width=0.5)"
]
Expand Down Expand Up @@ -3125,7 +3143,7 @@
"source": [
"## Add missing bounds for all axes supported by xcdat (X, Y, T, Z)\n",
"\n",
"* Related API: [xarray.Dataset.bounds.add_missing_bounds()](../generated/xarray.Dataset.bounds.add_missing_bounds.rst)"
"- Related API: [xarray.Dataset.bounds.add_missing_bounds()](../generated/xarray.Dataset.bounds.add_missing_bounds.rst)\n"
]
},
{
Expand Down Expand Up @@ -4542,24 +4560,21 @@
"\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",
"* Related API: [xcdat.get_dim_coords()](../generated/xcdat.get_dim_coords.rst)\n",
"- Related API: [xcdat.get_dim_coords()](../generated/xcdat.get_dim_coords.rst)\n",
"\n",
"Helpful knowledge:\n",
"\n",
"* 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",
"- 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",
"- 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",
" - **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",
" - **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"
"- 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"
]
},
{
Expand All @@ -4568,8 +4583,7 @@
"id": "15b5441d",
"metadata": {},
"source": [
"\n",
"### 1. `axis` attr"
"### 1. `axis` attr\n"
]
},
{
Expand Down Expand Up @@ -4598,7 +4612,7 @@
"id": "08505d5c",
"metadata": {},
"source": [
"### 2. `standard_name` attr"
"### 2. `standard_name` attr\n"
]
},
{
Expand Down
Loading

0 comments on commit d0e33aa

Please sign in to comment.