DOC: Polish tutorials (pik-copan#213)

Package sdist & repository: - add tutorial sources - remove generated files - remove datasets Code: - download datasets within notebooks - reduce redundancy - group dual pairs of plots - adjust some parameters - rerun notebooks Text & math: - fix typos, edit lightly, update references - fix TeX parsing errors in `nbsphinx` - optimise outline hierarchy for `nbsphinx
fkuehlein · Feb 6, 2024 · c5de131 · c5de131
1 parent aa39cf3
commit c5de131
Show file tree

Hide file tree

Showing 20 changed files with 982 additions and 1,512 deletions.
diff --git a/.gitignore b/.gitignore
@@ -72,6 +72,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/tutorials/images/
 
 # PyBuilder
 .pybuilder/
@@ -164,5 +165,6 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
-# Calculation dumps
+# cached data
 *.data
+examples/tutorials/data
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -4,6 +4,8 @@ recursive-include src/pyunicorn/*/_ext *.pxd *.pyx src_*.c
 
 include *.rst *.txt docs/Makefile
 graft docs/source
-recursive-include examples *.py
+recursive-include examples *.py *.ipynb *.png
+prune docs/source/tutorials/images
+prune **/.ipynb_checkpoints
 
 recursive-include tests *.py
diff --git a/docs/source/sitemap.rst b/docs/source/sitemap.rst
@@ -3,8 +3,7 @@ Sitemap
 =======
 
 .. toctree::
-    :maxdepth: 2
-    :includehidden:
+    :maxdepth: 3
 
     index
     download

diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
@@ -5,12 +5,11 @@ Tutorials
 The tutorials are designed to be self-explanatory, and are set up as Jupyter
 notebooks that can be accessed read-only through the links below. The original,
 executable notebook files can be found in the folder ``pyunicorn/examples``.
+For further details on the used classes and methods, please refer to the
+:doc:`api_doc` documentation.
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :glob:
 
-    tutorials/*
-
-For further details on the used classes and methods, please refer to the
-:doc:`api_doc` documentation.
+    tutorials/*
diff --git a/docs/source/tutorials/images/Characteristics_rP.png b/docs/source/tutorials/images/Characteristics_rP.png
diff --git a/docs/source/tutorials/images/ECA.png b/docs/source/tutorials/images/ECA.png
diff --git a/docs/source/tutorials/images/EventSynchronisation.png b/docs/source/tutorials/images/EventSynchronisation.png
diff --git a/docs/source/tutorials/images/REcurrencePlot_v2.png b/docs/source/tutorials/images/REcurrencePlot_v2.png
diff --git a/examples/tutorials/ClimateNetworks.ipynb b/examples/tutorials/ClimateNetworks.ipynb
diff --git a/examples/tutorials/CoupledClimateNetworks.ipynb b/examples/tutorials/CoupledClimateNetworks.ipynb
diff --git a/examples/tutorials/EventSeriesAnalysis.ipynb b/examples/tutorials/EventSeriesAnalysis.ipynb
diff --git a/examples/tutorials/RecurrenceNetworks.ipynb b/examples/tutorials/RecurrenceNetworks.ipynb
diff --git a/examples/tutorials/VisibilityGraphs.ipynb b/examples/tutorials/VisibilityGraphs.ipynb
diff --git a/examples/tutorials/data/air.mon.mean.nc b/examples/tutorials/data/air.mon.mean.nc
diff --git a/examples/tutorials/images/HVG.PNG b/examples/tutorials/images/HVG.PNG
diff --git a/docs/source/tutorials/images/HVG.PNG → examples/tutorials/images/HVG.png b/docs/source/tutorials/images/HVG.PNG → examples/tutorials/images/HVG.png
diff --git a/examples/tutorials/images/SimpleVG.PNG b/examples/tutorials/images/SimpleVG.PNG
diff --git a/docs/source/tutorials/images/SimpleVG.PNG → examples/tutorials/images/SimpleVG.png b/docs/source/tutorials/images/SimpleVG.PNG → examples/tutorials/images/SimpleVG.png
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -12,14 +12,40 @@
 # and J. Kurths, "Unified functional network and nonlinear time series analysis
 # for complex systems science: The pyunicorn package"
 
+from pathlib import Path
+
+import requests
 import pytest
 
 
 @pytest.fixture(scope="session",
                 params=["supremum", "euclidean", "manhattan"])
-def metric(request):
+def metric(request) -> str:
     '''
     A fixture for creating parametrized fixtures of classes that have a
     `metric` argument, as in `RecurrencePlot` and its child classes.
     '''
     return request.param
+
+
+@pytest.fixture(scope="session")
+def reanalysis_data() -> Path:
+    """
+    Locate, and potentially download, a small NOAA dataset. Currently used in:
+    - `tests/test_climate/test_map_plot.py`
+    - `examples/tutorials/ClimateNetworks.ipynb`
+    """
+    name = "air.mon.mean.nc"
+    path = Path("./examples/tutorials/data") / name
+    if not path.exists():
+        service = "https://psl.noaa.gov/repository/entry/get"
+        query = (
+            "entryid=synth%3Ae570c8f9-ec09-4e89-93b4-"
+            "babd5651e7a9%3AL25jZXAucmVhbmFseXNpcy5kZXJpdm"
+            "VkL3N1cmZhY2UvYWlyLm1vbi5tZWFuLm5j")
+        url = f"{service}/{name}?{query}"
+        res = requests.get(url, timeout=(20, 20))
+        res.raise_for_status()
+        with open(path, 'wb') as f:
+            f.write(res.content)
+    return path
diff --git a/tests/test_climate/test_map_plot.py b/tests/test_climate/test_map_plot.py
@@ -12,6 +12,8 @@
 # and J. Kurths, "Unified functional network and nonlinear time series analysis
 # for complex systems science: The pyunicorn package"
 
+from pathlib import Path
+
 import matplotlib.pyplot as plt
 
 from pyunicorn.climate.climate_data import ClimateData
@@ -26,20 +28,19 @@ class TestMapPlot:
     """
 
     @staticmethod
-    def test_plot():
+    def test_plot(reanalysis_data: Path):
         """
         Check error-free execution.
         """
         # prepare ClimateNetwork fixture
         # (select subset of data to speed up loading and calculation)
         title = "ncep_ncar_reanalysis"
-        file = 'examples/tutorials/data/air.mon.mean.nc'
         window = {
             "time_min": 0., "time_max": 0.,
             "lat_min": 30, "lon_min": 0,
             "lat_max": 50, "lon_max": 30}
         data = ClimateData.Load(
-            file_name=file, observable_name="air",
+            file_name=reanalysis_data, observable_name="air",
             file_type="NetCDF", window=window, time_cycle=12)
         net = TsonisClimateNetwork(data, threshold=.05, winter_only=False)