Merge pull request #409 from predictive-clinical-neuroscience/maint/add_federated_example

enh - add federated learning and evaluation metrics tutorials

Author: contsili

doc/convert_notebooks.py

@@ -1,33 +1,84 @@
+# To run this script, execute "python doc/convert_notebooks.py" from the root
+# of the repository.
+
 import glob
 import os
 import shutil
 import subprocess
+import sys
 
-EXAMPLES_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "examples"))
-TUTORIALS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "pages", "tutorials"))
+EXAMPLES_DIR = os.path.abspath(
+    os.path.join(os.path.dirname(__file__), "..", "examples")
+)
+TUTORIALS_DIR = os.path.abspath(
+    os.path.join(os.path.dirname(__file__), "pages", "tutorials")
+)
 
 os.makedirs(TUTORIALS_DIR, exist_ok=True)
 
 
-# Clean up old rst and support files in tutorials dir
-def clean_tutorials_dir():
+def clean_tutorials_dir() -> None:
+    """Remove previously generated RST files and support png's."""
+    # Delete every generated .rst file in the tutorials output dir
     for f in glob.glob(os.path.join(TUTORIALS_DIR, "*.rst")):
         os.remove(f)
+    # Delete every notebook-support directory that ends with "_files/".
+    # This deletes all the png's
     for d in glob.glob(os.path.join(TUTORIALS_DIR, "*_files")):
         shutil.rmtree(d)
 
 
-def convert_notebooks():
+def convert_notebooks() -> None:
+    """Convert every example notebook to RST using nbconvert.
+    """
+    # Collect all notebooks in the examples directory
     notebooks = glob.glob(os.path.join(EXAMPLES_DIR, "*.ipynb"))
+
     for nb_path in notebooks:
+        # Derive the rst filename from the notebook name
         nb_name = os.path.splitext(os.path.basename(nb_path))[0]
-        rst_path = os.path.join(TUTORIALS_DIR, f"{nb_name}.rst")
-        # Convert notebook to rst
+
         subprocess.run(
-            ["jupyter", "nbconvert", "--to", "rst", nb_path, "--output", nb_name, "--output-dir", TUTORIALS_DIR], check=True
+            [
+                sys.executable, # resolve "jupyter" from the virtual
+                                # environment that is running this script
+                "-m",
+                "jupyter",
+                "nbconvert", # nbconvert needs the package "pandoc". Please
+                             # install with
+                             # "conda install -c conda-forge pandoc"
+                "--to",
+                "rst",
+                nb_path,
+                "--output",
+                nb_name,
+                "--output-dir",
+                TUTORIALS_DIR,
+            ],
+            check=True,
         )
 
 
+def fix_image_paths() -> None:
+    """Fix image paths in generated RST files in Windows.
+    """    
+    # Iterate over every generated RST file in the tutorials dir
+    for rst_path in glob.glob(os.path.join(TUTORIALS_DIR, "*.rst")):
+        # Read the file content as text
+        with open(rst_path, "r", encoding="utf-8") as fh:
+            content = fh.read()
+
+        # Fix Windows paths
+        fixed = content.replace("%5C", "/")
+
+        # Only write back if the content actually changed
+        if fixed != content:
+            with open(rst_path, "w", encoding="utf-8") as fh:
+                fh.write(fixed)
+
+
 if __name__ == "__main__":
     clean_tutorials_dir()
     convert_notebooks()
+    if os.name == "nt": # Only fix image paths on Windows
+        fix_image_paths()

doc/index.rst

@@ -19,10 +19,11 @@ Welcome to PCNToolkit's documentation!
    pages/tutorials/04_HBR_SHASH.rst
    pages/tutorials/05_HBR_Beta.rst
    pages/tutorials/06_transfer_extend.rst
-   pages/tutorials/10_merge.rst
    pages/tutorials/07_model_comparison.rst
    pages/tutorials/08_cluster.rst
    pages/tutorials/09_command_line_interface.rst
+   pages/tutorials/12_federated_learning.rst
+   pages/tutorials/13_evaluation_metrics.rst
 
 
 .. toctree::

doc/pages/tutorials/01_loading_data.rst

@@ -65,7 +65,7 @@ Here are examples of both.
         	sex (2)
     	site (23)
         
-
+    
 
 
 
@@ -107,7 +107,7 @@ Here are examples of both.
         - 1 batch effects:
         	batch_effect_0 (2)
         
-
+    
 
 
 
@@ -1378,13 +1378,13 @@ values - ``statistic``: The name of the computed statistics
     Process: 75157 - 2025-11-20 13:18:58 - Computing yhat for WM-hypointensities.
     Process: 75157 - 2025-11-20 13:18:58 - Computing yhat for Left-Lateral-Ventricle.
     Process: 75157 - 2025-11-20 13:18:58 - Computing yhat for Brain-Stem.
-
+    
 
 .. parsed-literal::
 
     /opt/anaconda3/envs/ptk/lib/python3.12/site-packages/pcntoolkit/dataio/norm_data.py:1094: FutureWarning: The previous implementation of stack is deprecated and will be removed in a future version of pandas. See the What's New notes for pandas 2.1.0 for details. Specify future_stack=True to adopt the new implementation and silence this warning.
       subject_ids = subject_ids.stack(level="centile")
-
+    
 
 .. parsed-literal::
 
@@ -1407,7 +1407,7 @@ values - ``statistic``: The name of the computed statistics
     Process: 75157 - 2025-11-20 13:18:58 - Harmonizing data for Brain-Stem.
     Process: 75157 - 2025-11-20 13:18:59 - Saving model to:
     	/Users/stijndeboer/.pcntoolkit/saves.
-
+    
 
 .. code:: ipython3
 
@@ -2742,7 +2742,7 @@ applicable to both of them.
         	sex (2)
     	site (18)
         
-
+    
 
 .. code:: ipython3
 
@@ -2753,7 +2753,7 @@ applicable to both of them.
 .. parsed-literal::
 
     True
-
+    
 
 .. code:: ipython3
 

doc/pages/tutorials/02_BLR.rst

@@ -1,5 +1,5 @@
-Bayesian Linear Regression (BLR)
-================================
+Bayesian Linear Regression
+==========================
 
 Welcome to this tutorial notebook that will go through the fitting and
 evaluation of Normative models with Bayesian Linear Regression (BLR).
@@ -79,7 +79,7 @@ First we download a small example dataset from github.
         	sex (2)
     	site (23)
         
-
+    
 
 .. code:: ipython3
 
@@ -202,7 +202,7 @@ All results can be found in the save directory.
     Process: 75222 - 2025-11-20 13:13:43 - Fitting models on 4 response variables.
     Process: 75222 - 2025-11-20 13:13:43 - Fitting model for WM-hypointensities.
     Process: 75222 - 2025-11-20 13:13:44 - Fitting model for Right-Lateral-Ventricle.
-
+    
 
 .. parsed-literal::
 
@@ -258,12 +258,12 @@ All results can be found in the save directory.
       return f(*arrays, *other_args, **kwargs)
     /opt/anaconda3/envs/ptk/lib/python3.12/site-packages/scipy/_lib/_util.py:1226: LinAlgWarning: Ill-conditioned matrix (rcond=6.36754e-17): result may not be accurate.
       return f(*arrays, *other_args, **kwargs)
-
+    
 
 .. parsed-literal::
 
     Process: 75222 - 2025-11-20 13:13:46 - Fitting model for Right-Amygdala.
-
+    
 
 .. parsed-literal::
 
@@ -290,7 +290,7 @@ All results can be found in the save directory.
       return f(*arrays, *other_args, **kwargs)
     /opt/anaconda3/envs/ptk/lib/python3.12/site-packages/scipy/_lib/_util.py:1226: LinAlgWarning: Ill-conditioned matrix (rcond=1.95743e-41): result may not be accurate.
       return f(*arrays, *other_args, **kwargs)
-
+    
 
 .. parsed-literal::
 
@@ -341,7 +341,7 @@ All results can be found in the save directory.
     Process: 75222 - 2025-11-20 13:13:48 - Computing yhat for Right-Amygdala.
     Process: 75222 - 2025-11-20 13:13:48 - Saving model to:
     	resources/blr/save_dir.
-
+    
 
 
 
@@ -1182,7 +1182,7 @@ Let’s start with the centiles.
         scatter_data=train,  # Scatter this data along with the centiles
         batch_effects={"site": ["Beijing_Zang", "AnnArbor_a"], "sex": ["M"]},  # Highlight these groups
         show_other_data=True,  # scatter data not in those groups as smaller black circles
-        harmonize=True,  # harmonize the scatterdata, this means that we 'remove' the batch effects from the data, by simulating what the data would have looked like if all data was from the same batch.
+        harmonize_data=True,  # harmonize the scatterdata, this means that we 'remove' the batch effects from the data, by simulating what the data would have looked like if all data was from the same batch.
         show_yhat=True,
     )
 
@@ -1213,7 +1213,7 @@ Let’s start with the centiles.
     Process: 75222 - 2025-11-20 13:13:49 - Harmonizing data for WM-hypointensities.
     Process: 75222 - 2025-11-20 13:13:49 - Harmonizing data for CortexVol.
     Process: 75222 - 2025-11-20 13:13:49 - Harmonizing data for Right-Amygdala.
-
+    
 
 
 .. image:: 02_BLR_files/02_BLR_14_1.png
@@ -1301,7 +1301,7 @@ And finally the ridge plot:
       self._figure.tight_layout(*args, **kwargs)
     /opt/anaconda3/envs/ptk/lib/python3.12/site-packages/pcntoolkit/util/plotter.py:817: UserWarning: Tight layout not applied. tight_layout cannot make Axes height small enough to accommodate all Axes decorations.
       plt.tight_layout()
-
+    
 
 
 .. image:: 02_BLR_files/02_BLR_20_1.png
@@ -1321,7 +1321,7 @@ And finally the ridge plot:
       self._figure.tight_layout(*args, **kwargs)
     /opt/anaconda3/envs/ptk/lib/python3.12/site-packages/pcntoolkit/util/plotter.py:817: UserWarning: Tight layout not applied. tight_layout cannot make Axes height small enough to accommodate all Axes decorations.
       plt.tight_layout()
-
+    
 
 
 .. image:: 02_BLR_files/02_BLR_20_3.png
@@ -1341,7 +1341,7 @@ And finally the ridge plot:
       self._figure.tight_layout(*args, **kwargs)
     /opt/anaconda3/envs/ptk/lib/python3.12/site-packages/pcntoolkit/util/plotter.py:817: UserWarning: Tight layout not applied. tight_layout cannot make Axes height small enough to accommodate all Axes decorations.
       plt.tight_layout()
-
+    
 
 
 .. image:: 02_BLR_files/02_BLR_20_5.png
@@ -1361,7 +1361,7 @@ And finally the ridge plot:
       self._figure.tight_layout(*args, **kwargs)
     /opt/anaconda3/envs/ptk/lib/python3.12/site-packages/pcntoolkit/util/plotter.py:817: UserWarning: Tight layout not applied. tight_layout cannot make Axes height small enough to accommodate all Axes decorations.
       plt.tight_layout()
-
+    
 
 
 .. image:: 02_BLR_files/02_BLR_20_7.png
@@ -1642,7 +1642,7 @@ Predicting
     Process: 75222 - 2025-11-20 13:13:50 - Computing yhat for WM-hypointensities.
     Process: 75222 - 2025-11-20 13:13:50 - Computing yhat for CortexVol.
     Process: 75222 - 2025-11-20 13:13:50 - Computing yhat for Right-Amygdala.
-
+    
 
 
 
@@ -2502,7 +2502,7 @@ Harmonize
     Process: 75222 - 2025-11-20 13:13:51 - Harmonizing data for WM-hypointensities.
     Process: 75222 - 2025-11-20 13:13:51 - Harmonizing data for CortexVol.
     Process: 75222 - 2025-11-20 13:13:51 - Harmonizing data for Right-Amygdala.
-
+    
 
 
 .. image:: 02_BLR_files/02_BLR_27_1.png
@@ -2575,7 +2575,7 @@ site B.
     Process: 75222 - 2025-11-20 13:13:53 - Harmonizing data for WM-hypointensities.
     Process: 75222 - 2025-11-20 13:13:53 - Harmonizing data for CortexVol.
     Process: 75222 - 2025-11-20 13:13:53 - Harmonizing data for Right-Amygdala.
-
+    
 
 
 .. image:: 02_BLR_files/02_BLR_29_1.png
@@ -2641,7 +2641,7 @@ site B.
     Process: 75222 - 2025-11-20 13:13:53 - Harmonizing data for WM-hypointensities.
     Process: 75222 - 2025-11-20 13:13:53 - Harmonizing data for CortexVol.
     Process: 75222 - 2025-11-20 13:13:53 - Harmonizing data for Right-Amygdala.
-
+    
 
 
 .. image:: 02_BLR_files/02_BLR_30_1.png