Merge pull request #900 from sadielbartholomew/docs-summer-student-2025-recipes

Add three new recipes (21 - 23) by 2025 summer student

Author: sadielbartholomew

docs/source/_static/cf-recipe-placeholder-squarecrop.png

@@ -145,20 +145,20 @@ def _get_date():
 
 intersphinx_cache_limit = 5  # days to keep the cached inventories
 intersphinx_mapping = {
-    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
     "python": ("https://docs.python.org/3", None),
     "numpy": ("https://numpy.org/doc/stable", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
     #   'netCDF4': ("https://unidata.github.io/netcdf4-python", None),
     "cftime": ("https://unidata.github.io/cftime", None),
     "cfunits": ("https://ncas-cms.github.io/cfunits", None),
     "cfdm": ("https://ncas-cms.github.io/cfdm", None),
-    "cfplot": ("https://ncas-cms.github.io/cf-plot/build/", None),
+    "cfplot": ("https://ncas-cms.github.io/cf-plot", None),
     "dask": ("https://docs.dask.org/en/latest", None),
-    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
     # REVIEW: h5: new intersphinx mapping
     "h5netcdf": ("https://h5netcdf.org", None),
-    "zarr": ("https://zarr.readthedocs.io/en/stable/", None),
+    "zarr": ("https://zarr.readthedocs.io/en/stable", None),
 }
 
 # This extension is meant to help with the common pattern of having
@@ -387,16 +387,18 @@ def _get_date():
     "examples_dirs": "recipes",  # path to recipe files
     "gallery_dirs": "recipes",  # path to save gallery generated output
     "run_stale_examples": False,
-    "reference_url": {"cf": None},
+    # Below setting can be buggy: see:
+    # https://github.com/sphinx-gallery/sphinx-gallery/issues/967
+    #"reference_url": {"cf": None},
     "backreferences_dir": "gen_modules/backreferences",
     "doc_module": ("cf",),
     "inspect_global_variables": True,
     "within_subsection_order": FileNameSortKey,
-    "default_thumb_file": "_static/logo.svg",
+    "default_thumb_file": "_static/cf-recipe-placeholder-squarecrop.png",
     "image_scrapers": (
         "matplotlib",
     ),  # Ensures Matplotlib images are captured
-    "plot_gallery": "True",  # Enables plot rendering
+    "plot_gallery": True,  # Enables plot rendering
     "reset_modules": ("matplotlib",),  # Helps with memory management
     "capture_repr": (),
 }
@@ -473,7 +475,6 @@ def _get_date():
 
 import cf
 
-link_release = re.search("(\d+\.\d+\.\d+)", release).groups()[0]
 
 
 def linkcode_resolve(domain, info):
@@ -483,7 +484,6 @@ def linkcode_resolve(domain, info):
     #
     # >> rm -fr build/.doctrees build/*/.doctrees build/*/*/.doctrees
     # =================================================================
-
     online_source_code = True
 
     if domain != "py":
@@ -547,6 +547,8 @@ def linkcode_resolve(domain, info):
                 cfdm_version, fn, linespec
             )
         else:
+            link_release = re.search("(\d+\.\d+\.\d+)", release).groups()[0]
+
             # Point to on-line cf
             # code. E.g. https://github.com/NCAS-CMS/cf-python/blob/v3.0.1/cf/data/data.py#L4292
             url = "https://github.com/NCAS-CMS/cf-python/blob/v{0}/cf/{1}{2}".format(

docs/source/conf.py

@@ -116,13 +116,15 @@ ideas, code, and documentation to the cf library:
 * Bryan Lawrence
 * Charles Roberts
 * David Hassell
-* Evert Rol  
+* Evert Rol
+* George Pulickan
 * Javier Dehesa
 * Jonathan Gregory
 * Klaus Zimmermann
 * Kristian Sebastián
 * Mark Rhodes-Smith
 * Matt Brown
+* Natalia Hunt
 * Michael Decker
 * Oliver Kotla
 * Sadie Bartholomew

docs/source/contributing.rst

@@ -0,0 +1,77 @@
+"""
+Calculating global mean temperature timeseries
+==============================================
+
+In this recipe we will calculate and plot monthly and annual global mean temperature timeseries.
+"""
+
+# %%
+# 1. Import cf-python and cf-plot:
+
+import cfplot as cfp
+
+import cf
+
+# %%
+# 2. Read the field constructs:
+
+f = cf.read("~/recipes/cru_ts4.06.1901.2021.tmp.dat.nc")
+print(f)
+
+# %%
+# 3. Select near surface temperature by index and look at its contents:
+
+temp = f[1]
+print(temp)
+
+# %%
+# 4. Select latitude and longitude dimensions by identities, with two different techniques:
+
+lon = temp.coordinate("long_name=longitude")
+lat = temp.coordinate("Y")
+
+# %%
+# 5. Print the description of near surface temperature using the dump method to show properties of all constructs:
+
+temp.dump()
+
+# %%
+# 6. Latitude and longitude dimension coordinate cell bounds are absent, which are created and set:
+
+a = lat.create_bounds()
+lat.set_bounds(a)
+lat.dump()
+
+# %%
+
+b = lon.create_bounds()
+lon.set_bounds(b)
+lon.dump()
+
+# %%
+
+print(b.array)
+
+# %%
+# 7. Time dimension coordinate cell bounds are similarly created and set for cell sizes of one calendar month:
+
+time = temp.coordinate("long_name=time")
+c = time.create_bounds(cellsize=cf.M())
+time.set_bounds(c)
+time.dump()
+
+# %%
+# 8. Calculate and plot the area weighted mean surface temperature for each time:
+
+global_avg = temp.collapse("area: mean", weights=True)
+cfp.lineplot(global_avg, color="red", title="Global mean surface temperature")
+
+# %%
+# 9. Calculate and plot the annual global mean surface temperature:
+
+annual_global_avg = global_avg.collapse("T: mean", group=cf.Y())
+cfp.lineplot(
+    annual_global_avg,
+    color="red",
+    title="Annual global mean surface temperature",
+)

docs/source/images/data-operations-flowchart.png

@@ -0,0 +1,96 @@
+"""
+Calculating and plotting the global average temperature anomalies
+=================================================================
+
+In this recipe we will calculate and plot the global average temperature anomalies.
+"""
+
+# %%
+# 1. Import cf-python and cf-plot:
+
+import cfplot as cfp
+
+import cf
+
+# %%
+# 2. Read the field constructs:
+
+f = cf.read("~/recipes/cru_ts4.06.1901.2021.tmp.dat.nc")
+print(f)
+
+# %%
+# 3. Select near surface temperature by index and look at its contents:
+
+temp = f[1]
+print(temp)
+
+# %%
+# 4. Select latitude and longitude dimensions by identities, with two different techniques:
+
+lon = temp.coordinate("long_name=longitude")
+lat = temp.coordinate("Y")
+
+# %%
+# 5. Print the description of near surface temperature to show properties of all constructs:
+
+temp.dump()
+
+# %%
+# 6. Latitude and longitude dimension coordinate cell bounds are absent, which are created and set:
+
+a = lat.create_bounds()
+lat.set_bounds(a)
+lat.dump()
+
+# %%
+
+b = lon.create_bounds()
+lon.set_bounds(b)
+lon.dump()
+
+# %%
+
+print(b.array)
+
+# %%
+# 7. Time dimension coordinate cell bounds are similarly created and set for cell sizes of one calendar month:
+
+time = temp.coordinate("long_name=time")
+c = time.create_bounds(cellsize=cf.M())
+time.set_bounds(c)
+time.dump()
+
+# %%
+# 8. Calculate the area weighted mean surface temperature for each time using the collapse method:
+
+global_avg = temp.collapse("area: mean", weights=True)
+
+# %%
+# 9. Calculate the annual global mean surface temperature:
+
+annual_global_avg = global_avg.collapse("T: mean", group=cf.Y())
+
+# %%
+# 10. The temperature values are averaged for the climatological period of 1961-1990 by defining a subspace within these years using `cf.wi` query instance over subspace and doing a statistical collapse with the collapse method:
+
+annual_global_avg_61_90 = annual_global_avg.subspace(
+    T=cf.year(cf.wi(1961, 1990))
+)
+print(annual_global_avg_61_90)
+
+# %%
+
+temp_clim = annual_global_avg_61_90.collapse("T: mean")
+print(temp_clim)
+
+# %%
+# 11. The temperature anomaly is then calculated by subtracting these climatological temperature values from the annual global average temperatures and plotted:
+
+temp_anomaly = annual_global_avg - temp_clim
+cfp.lineplot(
+    temp_anomaly,
+    color="red",
+    title="Global Average Temperature Anomaly (1901-2021)",
+    ylabel="1961-1990 climatology difference ",
+    yunits="degree Celcius",
+)

docs/source/recipes/plot_01_recipe.py

@@ -0,0 +1,35 @@
+"""
+Plotting global mean temperatures spatially
+===========================================
+
+In this recipe, we will plot the global mean temperature spatially.
+"""
+
+# %%
+# 1. Import cf-python and cf-plot:
+
+import cfplot as cfp
+
+import cf
+
+# %%
+# 2. Read the field constructs:
+
+f = cf.read("~/recipes/cru_ts4.06.1901.2021.tmp.dat.nc")
+print(f)
+
+# %%
+# 3. Select near surface temperature by index and look at its contents:
+
+temp = f[1]
+print(temp)
+
+# %%
+# 4. Average the monthly mean surface temperature values by the time axis using the collapse method:
+
+global_avg = temp.collapse("mean", axes="long_name=time")
+
+# %%
+# 5. Plot the global mean surface temperatures:
+
+cfp.con(global_avg, lines=False, title="Global mean surface temperature")

docs/source/recipes/plot_02_recipe.py

@@ -0,0 +1,40 @@
+"""
+Comparing two datasets with different resolutions using regridding
+==================================================================
+
+In this recipe, we will regrid two different datasets with different resolutions. An example use case could be one where the observational dataset with a higher resolution needs to be regridded to that of the model dataset so that they can be compared with each other.
+"""
+
+# %%
+# 1. Import cf-python:
+
+import cf
+
+# %%
+# 2. Read the field constructs:
+
+obs = cf.read("~/recipes/cru_ts4.06.1901.2021.tmp.dat.nc", dask_chunks=None)
+print(obs)
+
+# %%
+
+model = cf.read(
+    "~/recipes/tas_Amon_HadGEM3-GC3-1_hist-1p0_r3i1p1f2_gn_185001-201412.nc"
+)
+print(model)
+
+# %%
+# 3. Select observation and model temperature fields by identity and index respectively, and look at their contents:
+
+obs_temp = obs.select_field("long_name=near-surface temperature")
+print(obs_temp)
+
+# %%
+
+model_temp = model[0]
+print(model_temp)
+
+# %%
+# 4. Regrid observational data to that of the model data and create a new low resolution observational data using bilinear interpolation:
+obs_temp_regrid = obs_temp.regrids(model_temp, method="linear")
+print(obs_temp_regrid)