Merge pull request #99 from ucl-cssb/examples-README

Consolidate examples documentation generation

Author: Fontanapink

docs/source/examples.rst

@@ -1,10 +1,73 @@
 Examples
 ========
 
-Below is an overview of the examples, organized by model type or analysis type.
+Jupyter Notebook Examples by Model
+------------------------------------
 
-.. include:: ../../examples/README.rst
-   :start-after: readme-begin
-   :end-before: readme-end
+Consumer Resource Model (CRM)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   notebooks/CRM/examples-sim-CRM
+
+Gaussian Processes (GP)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   notebooks/GP/examples-impute-GP
+   notebooks/GP/examples-impute-GP_Stein
+
+Multivariate Autoregressive Model (MVAR)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   notebooks/MVAR/examples-infer-MVAR
+   notebooks/MVAR/examples-sim-MVAR
+
+Multi-Model Analysis
+~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   notebooks/MultiModel/Herold/examples-Herold-VAR
+   notebooks/MultiModel/Herold/examples-Herold-sVAR
+   notebooks/MultiModel/Herold/examples_impute_data
+
+Vector Autoregression (VAR)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   notebooks/VAR/examples-bayes-VAR
+   notebooks/VAR/examples-sim-VAR
+
+Generalized Lotka-Volterra (gLV)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   notebooks/gLV/examples-Rutter-Dekker
+   notebooks/gLV/examples-Stein
+   notebooks/gLV/examples-bayes-gLV
+   notebooks/gLV/examples-lasso-gLV
+   notebooks/gLV/examples-ridge-gLV
+   notebooks/gLV/examples-sim-gLV
+
+Generalized Metabolic Lotka-Volterra (gMLV)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   notebooks/gMLV/examples-ridge-lasso-gMLV
+   notebooks/gMLV/examples-sim-gMLV
 
-.. include:: examples_auto.rst

docs/source/examples_auto.rst

@@ -3,6 +3,7 @@
 
 
 def clear_directory(directory):
+    """Clears the given directory, deleting all files and subfolders."""
     if os.path.exists(directory):
         for filename in os.listdir(directory):
             file_path = os.path.join(directory, filename)
@@ -15,6 +16,10 @@ def clear_directory(directory):
 
 
 def copy_notebooks(notebooks, examples_dir, target_dir):
+    """
+    Copies each notebook from the examples directory to the target directory.
+    The `notebooks` list contains paths relative to `examples_dir` (without the .ipynb extension).
+    """
     for nb in notebooks:
         source_path = os.path.join(examples_dir, f'{nb}.ipynb')
         target_path = os.path.join(target_dir, f'{nb}.ipynb')
@@ -25,87 +30,101 @@ def copy_notebooks(notebooks, examples_dir, target_dir):
 def find_notebooks(directory):
     """
     Returns a list of notebook paths (with no file extension),
-    relative to 'directory'. For example, if a notebook is:
+    relative to `directory`. For example, if a notebook is:
       examples/gLV/examples-bayes-gLV.ipynb
-    we return 'gLV/examples-bayes-gLV' (forward slashes).
+    this function returns 'gLV/examples-bayes-gLV' (using forward slashes).
     """
     notebooks = []
     for root, _, files in os.walk(directory):
         for file in files:
             if file.endswith(".ipynb"):
                 path = os.path.join(root, file)
                 relative_path = os.path.relpath(path, start=directory)
-                notebooks.append(
-                    relative_path.replace(
-                        os.path.sep, '/').replace('.ipynb', '')
-                )
+                notebooks.append(relative_path.replace(
+                    os.path.sep, '/').replace('.ipynb', ''))
     return notebooks
 
 
 def group_notebooks_by_top_dir(notebooks):
     """
-    Takes a list of relative notebook paths like ['gLV/examples-bayes-gLV', 'CRM/examples-sim-CRM']
-    and returns a dict grouping them by the top-level folder:
+    Groups a list of relative notebook paths (e.g. 'gLV/examples-bayes-gLV')
+    by their top-level folder.
+    Returns a dictionary, for example:
       {
-        'CRM': ['CRM/examples-sim-CRM'],
-        'gLV': ['gLV/examples-bayes-gLV']
-        ...
+          'CRM': ['CRM/examples-sim-CRM'],
+          'gLV': ['gLV/examples-bayes-gLV', 'gLV/examples-sim-gLV'],
+          ...
       }
     """
     grouped: dict[str, list[str]] = {}
     for nb in notebooks:
         parts = nb.split('/')
-        top_dir = parts[0]  # The directory before the first slash
+        top_dir = parts[0]
         grouped.setdefault(top_dir, []).append(nb)
     return grouped
 
 
-def generate_rst(notebooks, target_dir, output_file):
+def generate_rst(notebooks, output_file):
     """
-    Generates 'examples_auto.rst', grouping notebooks by their top-level folder.
-    Each folder gets its own subheading and toctree.
+    Generates a single 'examples.rst' file that includes a top-level header and,
+    for each model group, a section with a toctree of the notebooks.
     """
     grouped = group_notebooks_by_top_dir(notebooks)
 
+    # Mapping from folder name to a more descriptive title
+    MODEL_NAMES = {
+        "CRM": "Consumer Resource Model (CRM)",
+        "gLV": "Generalized Lotka-Volterra (gLV)",
+        "gMLV": "Generalized Metabolic Lotka-Volterra (gMLV)",
+        "GP": "Gaussian Processes (GP)",
+        "MVAR": "Multivariate Autoregressive Model (MVAR)",
+        "VAR": "Vector Autoregression (VAR)",
+        "MultiModel": "Multi-Model Analysis"
+    }
+
     with open(output_file, 'w', encoding='utf-8') as f:
+        # Write the top-level headers
+        f.write("Examples\n")
+        f.write("========\n\n")
         f.write("Jupyter Notebook Examples by Model\n")
-        f.write("----------------------------------\n\n")
+        f.write("------------------------------------\n\n")
 
-        # For each top-level folder, create a subheading and toctree
-        # Sort the folder names so the output is consistent
+        # For each top-level folder, generate a section with a toctree.
         for folder in sorted(grouped.keys()):
-            f.write(folder + "\n" + "-" * len(folder) + "\n\n")
+            title = MODEL_NAMES.get(folder, folder)
+            # Use a level-3 header (using '~' as the underline character)
+            f.write(f"{title}\n")
+            f.write("~" * len(title) + "\n\n")
             f.write(".. toctree::\n")
             f.write("   :maxdepth: 2\n\n")
-
-            # Write each notebook path
             for nb in sorted(grouped[folder]):
-                # notebooks are now in docs/source/notebooks
+                # Assume notebooks are in the 'notebooks' subfolder relative to the .rst file.
                 nb_path = os.path.join(
-                    'notebooks', nb).replace(os.path.sep, '/')
+                    "notebooks", nb).replace(os.path.sep, '/')
                 f.write(f"   {nb_path}\n")
-
-            f.write("\n")  # blank line between sections
+            f.write("\n")
 
 
 def main():
-    # Path to your top-level examples directory
-    examples_dir = os.path.abspath('../../examples')
+    # Path to your top-level examples directory (adjust relative path as needed)
+    examples_dir = os.path.abspath(os.path.join(
+        os.path.dirname(__file__), "../../examples"))
 
-    # The target dir in docs/source where notebooks will be copied
-    target_dir = os.path.join(os.path.dirname(__file__), 'notebooks')
+    # The target directory in docs/source where notebooks will be copied
+    target_dir = os.path.join(os.path.dirname(__file__), "notebooks")
 
     # Clear the target directory before re-copying notebooks
     clear_directory(target_dir)
 
+    # Find all notebooks in the examples directory
     notebooks = find_notebooks(examples_dir)
 
-    # Copy all notebooks from examples/ to docs/source/notebooks/
+    # Copy notebooks from examples/ to docs/source/notebooks/
     copy_notebooks(notebooks, examples_dir, target_dir)
 
-    # Generate 'examples_auto.rst' (instead of 'examples.rst')
-    output_rst = os.path.join(os.path.dirname(__file__), 'examples_auto.rst')
-    generate_rst(notebooks, target_dir, output_rst)
+    # Generate 'examples.rst' in the same directory as this script
+    output_rst = os.path.join(os.path.dirname(__file__), "examples.rst")
+    generate_rst(notebooks, output_rst)
     print(f"Generated {output_rst}")
 
 

docs/source/generate_examples_rst.py

@@ -279,7 +279,7 @@ def _run_inference_large(self, **kwargs) -> None:
             c2 = pm.InverseGamma("c2", 2, 8)
             tau = pm.HalfCauchy("tau", beta=tau0)
             lam = pm.HalfCauchy("lam", beta=1, shape=(ndim, ndim))
-            A = pm.Normal('A', mu=A_prior_mu, sigma=tau * lam * \
+            A = pm.Normal('A', mu=A_prior_mu, sigma=tau * lam *
                           at.sqrt(c2 / (c2 + tau**2 * lam**2)), shape=(ndim, ndim))
 
             # If noise covariance is provided, use it as a prior
@@ -438,14 +438,14 @@ def _run_inference_large_xs(self, **kwargs) -> None:
             c2_A = pm.InverseGamma("c2_A", 2, 1)
             tau_A = pm.HalfCauchy("tau_A", beta=tau0_A)
             lam_A = pm.HalfCauchy("lam_A", beta=1, shape=(nX, nX))
-            Ah = pm.Normal('Ah', mu=A_prior_mu, sigma=tau_A * lam_A * \
+            Ah = pm.Normal('Ah', mu=A_prior_mu, sigma=tau_A * lam_A *
                            at.sqrt(c2_A / (c2_A + tau_A**2 * lam_A**2)), shape=(nX, nX))
 
             tau0_B = (DB0 / (DB - DB0)) * 0.1 / np.sqrt(N)
             c2_B = pm.InverseGamma("c2_B", 2, 1)
             tau_B = pm.HalfCauchy("tau_B", beta=tau0_B)
             lam_B = pm.HalfCauchy("lam_B", beta=1, shape=(nS, nX))
-            Bh = pm.Normal('Bh', mu=0, sigma=tau_B * lam_B * \
+            Bh = pm.Normal('Bh', mu=0, sigma=tau_B * lam_B *
                            at.sqrt(c2_B / (c2_B + tau_B**2 * lam_B**2)), shape=(nS, nX))
 
             if noise_cov_prior is not None: