An explainable machine learning framework for ADHD classification using SHAP, Kernel PCA, neuroimaging, psychometric, and demographic data.
Recorded accuracy, F1, and ROC AUC for four fitted classifiers. These historical results are subject to the preprocessing-leakage limitation described below.
SHAP value distributions for the recorded XGBoost model, showing global model behavior rather than causal or clinical effects.
This project explores binary ADHD outcome classification from functional-connectome components, psychometric measures, and demographic variables. The recorded workflow merges 1,213 participant records, prepares a stratified 70/30 train/test split, reduces 19,900 connectome measurements to 20 radial-basis-function Kernel PCA components, evaluates four classifiers, and uses SHAP to inspect fitted-model behavior.
The repository preserves historical results as evidence of the original experiment. It does not present the model as a diagnostic system or as validated for clinical, regulatory, or production use.
| Publication boundary | Status |
|---|---|
| Scientific record | Historical notebooks and aggregate outputs preserved unchanged |
| Explainability | Global fitted-model inspection; no causal or individual interpretation |
| Data | Provider-controlled source and derived participant files are not distributed |
| Validation | Dataset-free checks verify notebook hashes, tracked-file boundaries, and links |
This is a retrospective machine learning project, not a medical device. Its predictions must not be used to diagnose, screen, treat, or make decisions about individuals. SHAP values describe associations within a fitted model; they do not establish causation. Sex-disaggregated metrics are exploratory subgroup comparisons, not a fairness certification.
| Area | Public reference |
|---|---|
| Intended and prohibited use | Model card · Responsible use |
| Data access and privacy | Dataset setup · Data directory |
| Scientific record | Historical methodology · Evaluation |
| Explainable AI | Explainability · Fairness and bias |
| Reproduction and integrity | Reproducibility · Notebook integrity |
| Legal and community | MIT License · Third-party notices · Contributing · Security |
- 1,213 merged participant records in the local source data
- 19,900 functional-connectome measurements per participant
- 10 selected numeric/psychometric features and 8 selected demographic features
- 20 Kernel PCA connectome components
- Logistic Regression, Random Forest, XGBoost, and LightGBM comparisons
- Five-fold stratified cross-validation with F1-based model selection
- Held-out accuracy, F1, ROC AUC, and confusion-matrix evaluation
- Tree SHAP global explanations for ensemble models
- Exploratory female/male subgroup metrics
The local project contains four inputs, all excluded from version control:
| Input | Recorded shape | Role |
|---|---|---|
| Labels | 1,213 × 3 | Participant ID, ADHD outcome, and Sex_F |
| Metadata A | 1,213 × 19 | Numeric psychometric and scan-age variables |
| Metadata B | 1,213 × 10 | Coded demographic and contextual variables |
| Connectome matrix | 1,213 × 19,901 | Participant ID plus 19,900 connectivity values |
The filenames and embedded workbook provenance are consistent with the WiDS Datathon 2025 Global Challenge, which describes data supplied by the Child Mind Institute's Healthy Brain Network. The local files do not include a license or terms document, so this attribution must be confirmed against the authors' original download before any data reuse.
No complete source, processed, split, or separate participant-level dataset is published here. The two approved notebooks preserve their historical embedded outputs, but those outputs are not a substitute for obtaining the dataset or accepting the provider's terms. Authorized users must obtain the data from the official Kaggle competition and comply with its current access, privacy, citation, and redistribution rules. A Kaggle account and acceptance of the applicable competition rules may be required. See dataset setup for the expected local filenames and publication boundary.
The recorded target is binary ADHD_Outcome. Sex_F is retained as a predictor and is also used for exploratory subgroup evaluation. The experiment does not establish diagnostic validity, treatment utility, or generalization beyond the recorded sample.
- Merge labels, numeric metadata, categorical metadata, and connectome values by
participant_id. - Create a combined sex/outcome label and make a 70/30 stratified split with
random_state=42. - Fit a five-neighbor KNN imputer on numeric training metadata and transform the test metadata.
- Fill missing coded demographic values with
3, described in the notebook as “Unknown.” - Rank numeric and demographic features with mutual information on the training partition; retain 10 and 8 features respectively.
- Standardize the connectome matrix and reduce it to 20 RBF Kernel PCA components (
gamma=0.001). - Merge selected metadata, connectome components,
Sex_F, and the outcome into 849-row training and 364-row test tables. - Standardize model inputs using training-set statistics while leaving
Sex_Funscaled.
The modeling notebook records five-fold StratifiedKFold cross-validation with shuffling and random_state=42. Logistic Regression uses grid search; the three ensemble models use randomized search with 10 sampled parameter combinations. F1 is the tuning score.
| Model | Recorded mean CV F1 | Accuracy | Test F1 | ROC AUC |
|---|---|---|---|---|
| Logistic Regression | 0.8088 | 0.8049 | 0.8493 | 0.8853 |
| Random Forest | 0.8548 | 0.8104 | 0.8681 | 0.8610 |
| XGBoost | 0.8554 | 0.8269 | 0.8777 | 0.8619 |
| LightGBM | 0.8529 | 0.7912 | 0.8555 | 0.8482 |
These are preserved notebook outputs, not recomputed metrics. XGBoost recorded the highest held-out accuracy and F1; Logistic Regression recorded the highest ROC AUC.
The experiment uses coefficient inspection for Logistic Regression and shap.TreeExplainer for Random Forest, XGBoost, and LightGBM. The selected XGBoost explanation is based on the 39-feature test representation: 10 selected numeric/psychometric features, 8 selected demographic features, 20 connectome Kernel PCA components, and Sex_F.
The SHAP plots provide global summaries across test examples. The repository does not record a separately constructed local explanation for a named individual, and no causal interpretation is claimed.
Metrics were calculated separately for the two recorded Sex_F groups. For XGBoost, the notebook records accuracy of 0.8240 and 0.8285, F1 of 0.8590 and 0.8858, and ROC AUC of 0.8712 and 0.8492 for female and male groups respectively.
No confidence intervals, hypothesis tests, calibration analysis, intersectional analysis, or external subgroup validation are recorded. Small observed gaps must not be described as statistical significance or universal fairness.
Recorded XGBoost confusion matrix: 75 true negatives, 40 false positives, 23 false negatives, and 226 true positives.
Mean absolute SHAP values for the recorded XGBoost model.
Exploratory metrics across the two recorded sex groups; this is not a fairness certification.
.
├── README.md
├── LICENSE
├── MODEL_CARD.md
├── RESPONSIBLE_USE.md
├── THIRD_PARTY_NOTICES.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
├── requirements.txt
├── .github/
│ ├── CODEOWNERS
│ ├── ISSUE_TEMPLATE/
│ ├── pull_request_template.md
│ └── workflows/
│ └── publication-validation.yml
├── scripts/
│ └── validate_publication.py
├── data/
│ └── README.md
├── processed_data/
│ └── README.md
├── final_data/
│ └── README.md
├── notebooks/
│ ├── README.md
│ ├── 01_data_exploration.ipynb
│ └── 02_modeling_and_testing.ipynb
└── docs/
├── DATASET_SETUP.md
├── METHODOLOGY.md
├── EVALUATION.md
├── EXPLAINABILITY.md
├── FAIRNESS_AND_BIAS.md
├── REPRODUCIBILITY.md
├── NOTEBOOK_INTEGRITY.md
└── images/
The two primary notebooks are included with their recorded saved outputs intact. They were not rerun during repository preparation. Checkpoint notebooks and generated train/test CSV files remain excluded. See notebooks/README.md.
Python, pandas, NumPy, Matplotlib, seaborn, scikit-learn, SHAP, XGBoost, LightGBM, OpenPyXL, and IPython. Notebook metadata records Python 3.12.7; compatibility with a clean environment has not been independently reproduced.
Create an isolated environment and install the verified direct dependencies:
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txtPlace authorized source files in data/. The included notebooks use notebooks/ as their working directory; their ../data and final_datasets paths are relative to that location.
The recorded local workflow is:
01_data_exploration.ipynb02_modeling_and_testing.ipynb
Obtain the original dataset independently and place the required files in data/ before execution. Running the first notebook writes derived CSV files under notebooks/final_datasets/, which remains ignored by Git.
- Notebook outputs, figures, and metrics were preserved without rerunning either notebook.
- Package versions were not recorded, so dependencies are intentionally unpinned.
- Random seeds are recorded for the split, mutual information, Kernel PCA, cross-validation, and model searches.
- No serialized fitted model is present.
- Exact end-to-end reproducibility has not been established in a clean environment.
See reproducibility for the preserved environment information and execution boundary.
Repository safeguards can be checked without installing project dependencies, obtaining data, or executing notebooks:
python scripts/validate_publication.pyThe validator reads the approved notebook bytes and tracked file paths. It fails on a notebook hash mismatch, an additional tracked notebook, tracked data-like files, missing required public files, or broken relative Markdown links. See notebook integrity.
Most importantly, the recorded preprocessing fits StandardScaler and Kernel PCA to the complete 1,213-row connectome matrix before selecting train and test rows. This exposes the dimensionality-reduction pipeline to held-out feature distributions and makes the reported test metrics optimistic as estimates of unseen-data performance. A future experiment should fit all learned preprocessing inside the training partition, preferably within each cross-validation fold, and then evaluate once on an untouched test set.
KNN imputation, mutual-information selection, connectome transformation, and model scaling are also established outside the cross-validation folds. In addition, the same held-out set is used to compare the four models and select XGBoost, so it is not an untouched post-selection test set.
Additional limitations include numeric treatment of coded demographic variables, a single internal split, no external validation, no confidence intervals, no probability calibration analysis, no decision-curve analysis, and no recorded statistical testing of subgroup differences. See historical methodology and evaluation.
The dataset concerns young participants and sensitive health-related characteristics. De-identification does not eliminate re-identification risk, and participant-level records must remain protected. The model is not clinically validated, is not a diagnosis tool, and should not be used for individual decisions. Any future use would require independent validation, governance, privacy review, bias analysis, and domain-expert oversight.
This project was developed by Alireza Zaeri and Fatemeh Sabourinia.
Public repository maintenance, contribution review, and security contact are handled by Fatemeh Sabourinia.
The project uses the WiDS Datathon 2025 Global Challenge dataset, derived from Healthy Brain Network data supplied by the Child Mind Institute. The official WiDS event page provides challenge context. Users must obtain the data directly from the official provider and comply with current access, citation, privacy, and usage terms. Dataset access and usage are not granted by any repository licence.
Eligible original public code and documentation are available under the MIT License. The licence does not cover the WiDS Datathon 2025 dataset, Healthy Brain Network data, Reproducible Brain Charts materials, participant-level files, derived datasets, restricted data-dictionary content, third-party dependencies, or external names and marks.
Dataset access and usage rights remain governed by the official provider's current terms. See third-party notices for the full boundary.