Ncl Climatology Entry (#80)

* climatology ncl entry and raw first take

* a few small changes

* add functions to index table

* Fix index and edit entry

* Add receipt and small changes

* Updates to entry

* add pyproject.toml file

* testing codespell

* typo and small changes

* typo

* use .codespellrc for now

* fix codespell config

* one more try on codespell

* fix links in table

* eol

* fix another link

* Update ncl/ncl_index/ncl-index-table.csv

Co-authored-by: Andy McKeen <amckeen@ucar.edu>

* adjust urls in ncl script

* updates to ncl index for consistency

* clear notebook outputs

* use geocat-datafiles

* appease pre-commit

* NCL and receipt updates to use new subsets and correct for calendar issues

* formatting

* tidy up the NCL entries notebook

* update to use new datafile

* review updates

* address comments in ncl index as well

* adjust rel_tol

* add note about calendar attribute to NCL script

* adjust tolerance again and comment

* formatting

* rel_tol to abs_tol

* rel_tol and abs_tol

* fix titles and labels

* whoops

---------

Co-authored-by: Katelyn FitzGerald <7872563+kafitzgerald@users.noreply.github.com>
Co-authored-by: Cora Schneck <22159116+cyschneck@users.noreply.github.com>

.codespellrc

@@ -1,3 +1,4 @@
 [codespell]
-skip=.git,*.pdf,*.svg
-ignore-regex=^\s*"image/\S+": ".*
+skip = .git,*.pdf,*.svg
+ignore-words-list = ond
+ignore-regex = ^\s*"image/\S+": ".*

ncl/ncl_entries/climatology_functions.ipynb

@@ -0,0 +1,330 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Climatology"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Overview\n",
+    "The NCL climatology functions listed below can be replicated using `xarray` and/or `geocat.comp`\n",
+    "\n",
+    "- [calcDayAnomTLL](https://www.ncl.ucar.edu/Document/Functions/Contributed/calcDayAnomTLL.shtml)\n",
+    "- [calcMonAnomTLL](https://www.ncl.ucar.edu/Document/Functions/Contributed/calcMonAnomTLL.shtml)\n",
+    "- [clmDayTLL](https://www.ncl.ucar.edu/Document/Functions/Contributed/clmDayTLL.shtml)\n",
+    "- [clmMonTLL](https://www.ncl.ucar.edu/Document/Functions/Contributed/clmMonTLL.shtml)\n",
+    "- [month_to_season](https://www.ncl.ucar.edu/Document/Functions/Contributed/month_to_season.shtml)\n",
+    "- [rmMonAnnCycTLL](https://www.ncl.ucar.edu/Document/Functions/Contributed/rmMonAnnCycTLL.shtml)\n",
+    "- [stdMonTLL](https://www.ncl.ucar.edu/Document/Functions/Contributed/stdMonTLL.shtml)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## calcDayAnomTLL\n",
+    "`calcDayAnomTLL` calculates daily anomalies from a daily data climatology"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Grab and Go"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import geocat.datafiles as gdf\n",
+    "from matplotlib import pyplot as plt\n",
+    "\n",
+    "ds = xr.open_dataset(gdf.get(\"applications_files/inputs/CMIP6_sea_ice_daily_subset.nc\"))\n",
+    "aice = ds.aice_d\n",
+    "DayTLL = aice.groupby(aice.time.dt.dayofyear)\n",
+    "clmDayTLL = DayTLL.mean(dim=\"time\")\n",
+    "calcDayAnomTLL = DayTLL - clmDayTLL\n",
+    "\n",
+    "calcDayAnomTLL = calcDayAnomTLL.assign_attrs(long_name=\"sea ice anomaly\")\n",
+    "\n",
+    "calcDayAnomTLL[0, :, :].plot();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## calcMonAnomTLL\n",
+    "`calcMonAnomTLL` calculates monthly anomalies by subtracting the long-term mean from each point"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Grab and Go"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import geocat.datafiles as gdf\n",
+    "\n",
+    "ds = xr.open_dataset(\n",
+    "    gdf.get(\"applications_files/inputs/CMIP6_sea_ice_monthly_subset.nc\")\n",
+    ")\n",
+    "aice = ds.aice\n",
+    "MonTLL = aice.groupby(aice.time.dt.month)\n",
+    "clmMonTLL = MonTLL.mean(dim=\"time\")\n",
+    "calcMonAnomTLL = MonTLL - clmMonTLL\n",
+    "\n",
+    "calcMonAnomTLL = calcMonAnomTLL.assign_attrs(long_name=\"sea ice anomaly\")\n",
+    "\n",
+    "calcMonAnomTLL[0, :, :].plot();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## clmDayTLL\n",
+    "`clmDayTLL` calculates long-term daily means (daily climatology) from daily data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Grab and Go"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import geocat.datafiles as gdf\n",
+    "\n",
+    "ds = xr.open_dataset(gdf.get(\"applications_files/inputs/CMIP6_sea_ice_daily_subset.nc\"))\n",
+    "aice = ds.aice_d\n",
+    "DayTLL = aice.groupby(aice.time.dt.dayofyear)\n",
+    "clmDayTLL = DayTLL.mean(dim=\"time\")\n",
+    "\n",
+    "clmDayTLL[:, 10, 10].plot()\n",
+    "plt.title(\"daily climatology\")\n",
+    "plt.xlabel(\"day of year\")\n",
+    "plt.ylabel(\"sea ice area\");"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## clmMonTLL\n",
+    "`clmMonTLL` calculates long-term monthly means (monthly climatology) from monthly data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Grab and Go"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import geocat.datafiles as gdf\n",
+    "\n",
+    "ds = xr.open_dataset(\n",
+    "    gdf.get(\"applications_files/inputs/CMIP6_sea_ice_monthly_subset.nc\")\n",
+    ")\n",
+    "aice = ds.aice\n",
+    "MonTLL = aice.groupby(aice.time.dt.month)\n",
+    "clmMonTLL = MonTLL.mean(dim=\"time\")\n",
+    "\n",
+    "clmMonTLL[:, 10, 10].plot()\n",
+    "plt.title(\"monthly climatology\")\n",
+    "plt.xlabel(\"month of year\")\n",
+    "plt.ylabel(\"sea ice area\");"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## month_to_season\n",
+    "`month_to_season` computes a user-specified three-month seasonal mean (DJF, JFM, FMA, MAM, AMJ, MJJ, JJA, JAS, ASO, SON, OND, NDJ)\n",
+    "\n",
+    "```{note}\n",
+    "You can do something similar with directly with Xarray as shown in [this example in the Xarray documentation](https://docs.xarray.dev/en/stable/examples/monthly-means.html#Calculating-Seasonal-Averages-from-Time-Series-of-Monthly-Means). However, it requires substantially more code and doesn't have as much flexibility with respect to how the seasons are defined.\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Grab and Go"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import geocat.datafiles as gdf\n",
+    "from geocat.comp import month_to_season\n",
+    "\n",
+    "ds = xr.open_dataset(\n",
+    "    gdf.get(\"applications_files/inputs/CMIP6_sea_ice_monthly_subset.nc\")\n",
+    ")\n",
+    "aice = ds.aice\n",
+    "mon_to_season = month_to_season(aice, \"ASO\")\n",
+    "\n",
+    "mon_to_season = mon_to_season.assign_attrs(long_name=\"sea ice area\")\n",
+    "\n",
+    "mon_to_season[0, :, :].plot()\n",
+    "\n",
+    "plt.title(\"2010 seasonal mean\");"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## rmMonAnnCycTLL\n",
+    "`rmMonAnnCycTLL` removes the annual cycle from monthly data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Grab and Go"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import geocat.datafiles as gdf\n",
+    "\n",
+    "ds = xr.open_dataset(\n",
+    "    gdf.get(\"applications_files/inputs/CMIP6_sea_ice_monthly_subset.nc\")\n",
+    ")\n",
+    "aice = ds.aice\n",
+    "MonTLL = aice.groupby(aice.time.dt.month)\n",
+    "clmMonTLL = MonTLL.mean(dim=\"time\")\n",
+    "rmMonAnnCycTLL = MonTLL - clmMonTLL\n",
+    "\n",
+    "rmMonAnnCycTLL[:, 10, 10].plot()\n",
+    "plt.title(\"annual cycle removed\")\n",
+    "plt.ylabel(\"sea ice area\");"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## stdMonTLL\n",
+    "`stdMonTLL` calculates standard deviations of monthly means"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Grab and Go"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import geocat.datafiles as gdf\n",
+    "\n",
+    "ds = xr.open_dataset(\n",
+    "    gdf.get(\"applications_files/inputs/CMIP6_sea_ice_monthly_subset.nc\")\n",
+    ")\n",
+    "aice = ds.aice\n",
+    "MonTLL = aice.groupby(aice.time.dt.month)\n",
+    "stdMonTLL = MonTLL.std(ddof=1)\n",
+    "\n",
+    "stdMonTLL[0, :, :].plot();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Python Resources\n",
+    "\n",
+    "- GeoCAT Applications [climatology page](https://ncar.github.io/geocat-applications/applications/data_analysis/climatology.html)\n",
+    "- Climatematch Academy [Xarray Data Analysis and Climatology tutorial](https://comptools.climatematch.io/tutorials/W1D1_ClimateSystemOverview/student/W1D1_Tutorial5.html)\n",
+    "- Project Pythia Foundations [Computations and Masks with Xarray tutorial](https://foundations.projectpythia.org/core/xarray/computation-masking.html)\n",
+    "- Xarray User Guide [section on time series data](https://docs.xarray.dev/en/stable/user-guide/time-series.html)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

ncl/ncl_entries/ncl_entries.rst

@@ -8,6 +8,7 @@ Data Analysis
 .. toctree::
     :maxdepth: 1
 
+    climatology_functions.ipynb
     trigonometric_functions.ipynb
     general_applied_math.ipynb
     specx_specxy_anal.ipynb

ncl/ncl_index/ncl-index-table.csv

@@ -9,8 +9,15 @@ NCL Function,Description,Python Equivalent,Notes
 `cosh <https://www.ncl.ucar.edu/Document/Functions/Built-in/cosh.shtml>`__,"Computes the hyperbolic cosine of numeric types","``math.cosh()`` or ``numpy.cosh()``",`example notebook <../ncl_entries/trigonometric_functions.ipynb#cosh>`__
 `sinh <https://www.ncl.ucar.edu/Document/Functions/Built-in/sinh.shtml>`__,"Computes the hyperbolic sine of numeric types","``math.sinh()`` or ``numpy.sinh()``",`example notebook <../ncl_entries/trigonometric_functions.ipynb#sinh>`__
 `tanh <https://www.ncl.ucar.edu/Document/Functions/Built-in/tanh.shtml>`__,"Computes the hyperbolic tangent of numeric types","``math.tanh()`` or ``numpy.tanh()``",`example notebook <../ncl_entries/trigonometric_functions.ipynb#tanh>`__
-`days_in_month <https://www.ncl.ucar.edu/Document/Functions/Built-in/days_in_month.shtml>`__,"Calculates the number of days in a month given month and year","``cftime.datetime().daysinmonth``",`example notebook <../ncl_entries/days_in_month.ipynb>`__
-`day_of_week <https://www.ncl.ucar.edu/Document/Functions/Built-in/day_of_week.shtml>`__,"Calculates the day of the week given month, day, and year","``cftime.datetime().dayofwk``",`example notebook <../ncl_entries/day_of_week.ipynb>`__
+`days_in_month <https://www.ncl.ucar.edu/Document/Functions/Built-in/days_in_month.shtml>`__,"Calculates the number of days in a month given month and year","``cftime.datetime()``",`example notebook <../ncl_entries/days_in_month.ipynb>`__
+`day_of_week <https://www.ncl.ucar.edu/Document/Functions/Built-in/day_of_week.shtml>`__,"Calculates the day of the week given month, day, and year","``cftime.datetime()``",`example notebook <../ncl_entries/day_of_week.ipynb>`__
+`calcDayAnomTLL <https://www.ncl.ucar.edu/Document/Functions/Contributed/calcDayAnomTLL.shtml>`__,"Calculates daily anomalies from a daily data climatology","``xarray.DataArray.groupby()``",`example notebook <../ncl_entries/climatology_functions.ipynb#calcdayanomtll>`__
+`calcMonAnomTLL <https://www.ncl.ucar.edu/Document/Functions/Contributed/calcMonAnomTLL.shtml>`__,"Calculates monthly anomalies by subtracting the long-term mean from each point","``xarray.DataArray.groupby()``",`example notebook <../ncl_entries/climatology_functions.ipynb#calcmonanomtll>`__
+`clmDayTLL <https://www.ncl.ucar.edu/Document/Functions/Contributed/clmDayTLL.shtml>`__,"Calculates long-term daily means (daily climatology) from daily data","``xarray.DataArray.groupby()``",`example notebook <../ncl_entries/climatology_functions.ipynb#clmdaytll>`__
+`clmMonTLL <https://www.ncl.ucar.edu/Document/Functions/Contributed/clmMonTLL.shtml>`__,"Calculates long-term monthly means (monthly climatology) from monthly data","``xarray.DataArray.groupby()``",`example notebook <../ncl_entries/climatology_functions.ipynb#clmmontll>`__
+`month_to_season <https://www.ncl.ucar.edu/Document/Functions/Contributed/month_to_season.shtml>`__,"Computes a user-specified three-month seasonal mean","``geocat.comp.month_to_season()``",`example notebook <../ncl_entries/climatology_functions.ipynb#month-to-season>`__
+`rmMonAnnCycTLL <https://www.ncl.ucar.edu/Document/Functions/Contributed/rmMonAnnCycTLL.shtml>`__,"Removes the annual cycle from monthly data","``xarray.DataArray.groupby()``",`example notebook <../ncl_entries/climatology_functions.ipynb#rmmonanncyctll>`__
+`stdMonTLL <https://www.ncl.ucar.edu/Document/Functions/Contributed/stdMonTLL.shtml>`__,"Calculates standard deviations of monthly means","``xarray.DataArray.groupby()``",`example notebook <../ncl_entries/climatology_functions.ipynb#stdmontll>`__
 `abs <https://www.ncl.ucar.edu/Document/Functions/Built-in/abs.shtml>`__,"Returns the absolute value of numeric data","``abs()`` or ``numpy.abs()``",`example notebook <../ncl_entries/general_applied_math.ipynb#abs-fabs>`__
 `avg <https://www.ncl.ucar.edu/Document/Functions/Built-in/avg.shtml>`__,"Computes the average of a variable regardless of dimensionality","``numpy.average()`` or ``numpy.mean()``",`example notebook <../ncl_entries/general_applied_math.ipynb#avg>`__
 `cumsum <https://www.ncl.ucar.edu/Document/Functions/Built-in/cumsum.shtml>`__,"Calculates the cumulative sum","``numpy.cumsum()``",`example notebook <../ncl_entries/general_applied_math.ipynb#cumsum>`__