Brain disorder diagnosis notebook rework

[zaRizk7]

This PR introduces an almost complete rework of the brain disorder diagnosis tutorial notebook and some changes regarding the structure to store resources for the book (e.g., logo and icon).

Notebook

• Complete restructure of the notebook per-agreed structure.
• Adds introduction to the problem and multi-site data with ABIDE and why integrating the data remains a challenge particularly for ML.
• Adds problem formulation and solution similar to the ones in Kunda et al. (2022).
• Adds an objective following the produced flowchart, which describes the modeling pipeline and its associated PyKale (or other libraries) module.
• Adds base.yml files for both lpgo and skf evaluation.
• Include small config subsets that can be modified during runtime.
• Adds quizzes for several sections.
• Adds visualization for functional connectivity and phenotypic data distribution (before and after preprocessing).
• Adds illustration for comparing lpgo and skf.
• Include skf experiment result to compare with the default lpgo runtime used for the experiment to highlight the improvements when applying MIDA.
• Adds extra tasks for exploration.
• Include quiz solutions at the end.
• Includes tmi2022.yml file to replicate the param grid found in Kunda et al. (2022)'s source code.
• Adds estimated Colab runtime on package installation and training.

Helper Functions

• Include visualization.py to aid in visualizing phenotypic data distributions and FCs.
• Adds parse_param_grid to parsing to workaround yacs limitation to dynamically define param_grid.
• Includes top_k_sites in load_data from data.py to sample the k-largest sites.
• Include top_k_sites in config.py.

Book Project Structure Reorganization

• Adds favicon.ico icon.
• Reorganized the logo and icon, moved to resources.
• Include sphinx_exercise to aid in generating RST-style exercise.
• Include torch-geometric and sphinx_exercise in requirements.py.
• Updates nilearn version.

Note

• Once merged, the branch specified in the notebook needs to be changed to clone the main branch.
• The figures will only be properly rendered in jupyter-book, the Colab runtime will not render it as it doesn't support RST rendering.

[Copilot]

Pull Request Overview

This PR introduces a comprehensive rework of the brain disorder diagnosis tutorial notebook along with several updates in helper functions, configuration, and experiment setup files.

• Restructures the diagnostic notebook and adds new visualization and helper functions.
• Updates preprocessing logic (including a change in handedness mapping) and extends parameter parsing.
• Revises YAML experiment configuration files and project config for improved resource management.

Reviewed Changes

Copilot reviewed 10 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tutorials/brain-disorder-diagnosis/visualization.py	Adds functions to plot phenotypic distributions and functional connectivity matrices.
tutorials/brain-disorder-diagnosis/preprocess.py	Updates phenotypic data processing, including a change in handedness mapping and an option to one-hot encode categories.
tutorials/brain-disorder-diagnosis/parsing.py	Introduces the parse_param_grid helper function for dynamic hyperparameter grid construction.
tutorials/brain-disorder-diagnosis/experiments/skf/tmi2022.yml	Defines configuration for skf experiments including cross-validation and parameter grid settings.
tutorials/brain-disorder-diagnosis/experiments/skf/base.yml	Provides baseline settings for skf experiments including dataset and trainer configurations.
tutorials/brain-disorder-diagnosis/experiments/lpgo/tmi2022.yml	Sets up configuration for lpgo experiments with updated parameter grid values.
tutorials/brain-disorder-diagnosis/experiments/lpgo/base.yml	Updates baseline experiment settings for the lpgo pipeline, including an increased NUM_SEARCH_ITER value.
tutorials/brain-disorder-diagnosis/data.py	Adds support for selecting the top K sites when loading data to filter subjects by site frequency.
tutorials/brain-disorder-diagnosis/config.py	Renames and adds configuration keys (e.g., DATA_DIR, TOP_K_SITES) for improved resource handling.
_config.yml	Updates project configuration with new logo and favicon paths along with additional Sphinx extensions.

Comments suppressed due to low confidence (2)

tutorials/brain-disorder-diagnosis/preprocess.py:36

• The mapping for handedness has changed from 'LEFT' to 'RIGHT' for both '-9999' and np.nan. Verify that this change aligns with the intended diagnostic criteria.

        "-9999": "RIGHT",

tutorials/brain-disorder-diagnosis/experiments/lpgo/base.yml:10

• [nitpick] Increasing NUM_SEARCH_ITER to 100 may significantly impact computation time; confirm that this value is optimal for the intended performance requirements.

  NUM_SEARCH_ITER: 100

[Copilot]

Consider quoting the values 'pre', 'post', and 'null' in the parameter grid to ensure they are parsed as strings in YAML.

Suggested change

	- [domain_adapter__augment, [pre, post, null]]
	- [domain_adapter__augment, ['pre', 'post', 'null']]

[zaRizk7]

Using 'null' might made yacs mis-parsed it as a string, as the expected result is null = None.

[Copilot]

Consider quoting the values 'pre', 'post', and 'null' in the parameter grid to ensure they are parsed as strings in YAML.

Suggested change

	- [domain_adapter__augment, [pre, post, null]]
	- [domain_adapter__augment, ['pre', 'post', 'null']]

[zaRizk7]

Using 'null' might made yacs mis-parsed it as a string, as the expected result is null = None.