Brain disorder diagnosis notebook rework

_config.yml

@@ -3,7 +3,8 @@
 
 title: PyKale
 author: PyKale Contributors
-logo: EMBC_logo.png
+logo: resources/embc_logo.png
+copyright: 2025
 
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
@@ -33,6 +34,12 @@ repository:
 html:
   use_issues_button: true
   use_repository_button: true
+  favicon: resources/icon.ico
+
+sphinx:
+  extra_extensions:
+    - sphinx_exercise
+    - sphinx_togglebutton
 
 # Only works for .ipynb files
 launch_buttons:

requirements.txt

@@ -1,8 +1,21 @@
+# Requirements for the book itself
 jupyter-book==1.0.4.post1
+sphinx-exercise==1.0.1
+
+# Visualization tools
 matplotlib==3.10.3
 seaborn==0.13.2
+
+# Data loading, processing, and manipulation
 numpy==1.26.4
-git+https://github.com/pykale/pykale@main
-nilearn==0.10.4
-yacs==0.1.8
 gdown==5.2.0
+
+# PyKale latest version
+git+https://github.com/pykale/pykale@main
+
+# Additional dependencies for the tutorial notebooks
+nilearn==0.12.0
+torch==2.3.0
+torch-geometric==2.3.0
+torch-sparse
+torch-scatter

tutorials/brain-disorder-diagnosis/config.py

@@ -6,7 +6,7 @@
 # Dataset configuration
 _C.DATASET = CfgNode()
 # Path to the dataset directory
-_C.DATASET.PATH = "data"
+_C.DATASET.DATA_DIR = "data"
 # Name of the brain atlas to use
 # Available options:
 # - "aal" (AAL)
@@ -27,6 +27,8 @@
 # - "covariance"
 # - "tangent-pearson"
 _C.DATASET.FC = "tangent-pearson"
+# Number of top sites to load for the runtime.
+_C.DATASET.TOP_K_SITES = None
 
 # Phenotype configuration
 _C.PHENOTYPE = CfgNode()
@@ -57,6 +59,11 @@
 # - "ridge"
 # - "auto"
 _C.TRAINER.CLASSIFIER = "lr"
+# Parameter grid for hyperparameter tuning
+# We use list of pairs directly instead of CfgNode for flexibility
+# As a workaround for yacs limitation, we use None to indicate
+# that we're using the large set of default hyperparameters.
+_C.TRAINER.PARAM_GRID = None
 # Use non-linear transformations (no interpretability)
 _C.TRAINER.NONLINEAR = False
 # Search strategy for hyperparameter tuning

tutorials/brain-disorder-diagnosis/data.py

@@ -4,7 +4,12 @@
 import pandas as pd
 import gdown
 
-from sklearn.utils._param_validation import StrOptions, validate_params
+from sklearn.utils._param_validation import (
+    StrOptions,
+    validate_params,
+    Interval,
+    Integral,
+)
 
 
 @validate_params(
@@ -28,12 +33,18 @@
             )
         ],
         "vectorize": ["boolean"],
+        "top_k_sites": [None, Interval(Integral, 1, None, closed="left")],
         "verbose": ["boolean"],
     },
     prefer_skip_nested_validation=False,
 )
 def load_data(
-    data_dir="data", atlas="cc200", fc="tangent-pearson", vectorize=True, verbose=True
+    data_dir="data",
+    atlas="cc200",
+    fc="tangent-pearson",
+    vectorize=True,
+    top_k_sites=None,
+    verbose=True,
 ):
     """
     Load functional connectivity data and phenotypic data with gdown support.
@@ -55,6 +66,10 @@ def load_data(
     vectorize : bool, optional (default=True)
         Whether to vectorize the upper triangle of the connectivity matrices.
 
+    top_k_sites : int or None, optional (default=None)
+        If specified, only the top K sites with the most subjects will be used.
+        If None, all sites will be used.
+
     verbose : bool, optional (default=True)
         Whether to print download and progress messages.
 
@@ -101,6 +116,17 @@ def load_data(
         rois = np.array(f.read().strip().split("\n"))
     coords = np.load(os.path.join(atlas_path, "coords.npy"))
 
+    sites = phenotypes["SITE_ID"].value_counts()
+    if top_k_sites is not None:
+        if top_k_sites > len(sites):
+            raise ValueError(
+                f"top_k_sites ({top_k_sites}) cannot be greater than the number of sites ({len(sites)})"
+            )
+        top_sites = sites.nlargest(top_k_sites).index
+        mask = phenotypes["SITE_ID"].isin(top_sites)
+        phenotypes = phenotypes[mask]
+        fc_data = fc_data[mask]
+
     return fc_data, phenotypes, rois, coords
 
 

tutorials/brain-disorder-diagnosis/experiments/base.yml → tutorials/brain-disorder-diagnosis/experiments/lpgo/base.yml

@@ -1,11 +1,13 @@
 DATASET:
   ATLAS: hcp-ica
+  TOP_K_SITES: 10
 
 CROSS_VALIDATION:
-  NUM_REPEATS: 1
+  SPLIT: lpgo
+  NUM_FOLDS: 1
 
 TRAINER:
-  NUM_SEARCH_ITER: 20
+  NUM_SEARCH_ITER: 100
   NUM_SOLVER_ITER: 100
 
 RANDOM_STATE: 0

tutorials/brain-disorder-diagnosis/experiments/lpgo/tmi2022.yml

@@ -0,0 +1,15 @@
+CROSS_VALIDATION:
+  SPLIT: lpgo
+  NUM_FOLDS: 1
+
+TRAINER:
+  CLASSIFIER: ridge
+  PARAM_GRID:
+    - [alpha, [0.25, 0.5, 0.75, 1.0]]
+    - [domain_adapter__num_components, [50, 150, 300]]
+    - [domain_adapter__mu, [0.25, 0.5, 0.75, 1.0]]
+    - [domain_adapter__ignore_y, [True]]
+    - [domain_adapter__augment, [pre, post, null]]
+  SEARCH_STRATEGY: grid
+
+RANDOM_STATE: 0

tutorials/brain-disorder-diagnosis/experiments/skf/base.yml

@@ -0,0 +1,14 @@
+DATASET:
+  ATLAS: hcp-ica
+  TOP_K_SITES: 10
+
+CROSS_VALIDATION:
+  SPLIT: skf
+  NUM_FOLDS: 5
+  NUM_REPEATS: 2
+
+TRAINER:
+  NUM_SEARCH_ITER: 100
+  NUM_SOLVER_ITER: 100
+
+RANDOM_STATE: 0

tutorials/brain-disorder-diagnosis/experiments/skf/tmi2022.yml

@@ -0,0 +1,16 @@
+CROSS_VALIDATION:
+  SPLIT: skf
+  NUM_FOLDS: 10
+  NUM_REPEATS: 5
+
+TRAINER:
+  CLASSIFIER: ridge
+  PARAM_GRID:
+    - [alpha, [0.25, 0.5, 0.75, 1.0]]
+    - [domain_adapter__num_components, [50, 150, 300]]
+    - [domain_adapter__mu, [0.25, 0.5, 0.75, 1.0]]
+    - [domain_adapter__ignore_y, [True]]
+    - [domain_adapter__augment, [pre, post, null]]
+  SEARCH_STRATEGY: grid
+
+RANDOM_STATE: 0