# aditsawhney/adhd-project architecture

> Architecture diagram of the GitHub repository aditsawhney/adhd-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aditsawhney/adhd-project
- Repository: https://github.com/aditsawhney/adhd-project

## Overview

NeuroNova is a research pipeline comparing ADHD classification from pre-assessment features (Model B) with an extended clinical feature set (Model A), then auditing test performance and fairness. The workflow cleans and audits ADHD-200 data, creates a shared stratified split, trains calibrated model ensembles, and evaluates both on the same test rows. A secondary branch fits standalone Model A XGBoost for SHAP analysis. The graph follows README-documented phases and sampled source calls; unsampled implementation details are omitted.

Main entry points: [`src/neuronova/train.py`](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/train.py) (Selection and ensembles), [`src/neuronova/evaluate.py`](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/evaluate.py) (Test evaluation), [`data/processed`](https://github.com/aditsawhney/adhd-project/tree/main/data/processed) (Shared data splits), [`src/neuronova/shap_analysis.py`](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/shap_analysis.py) (Standalone SHAP check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_raw_csv["Raw phenotypes"]
  node_clean_audit["Clean and audit<br/>[data.py]"]
  node_cleaned_data["Cleaned data<br/>[cleaned_full.csv]"]
  node_split_preprocess["Split and preprocess<br/>[features.py]"]
  node_splits[("Shared data splits")]
end

subgraph group_models["Model tracks"]
  node_model_b_features["Pre-assessment features<br/>[features.py]"]
  node_model_a_features["Extended features<br/>[features.py]"]
  node_training["Selection and ensembles<br/>[train.py]"]
  node_model_artifacts[("Trained models")]
  node_selection_reports[("Selection results")]
end

subgraph group_assessment["Evaluation and explanation"]
  node_evaluation["Test evaluation<br/>[evaluate.py]"]
  node_fairness["Sex and age audit<br/>[evaluate.py]"]
  node_comparison["Model comparison"]
  node_evaluation_reports[("Metrics and plots")]
  node_shap_check["Standalone SHAP check<br/>[shap_analysis.py]"]
  node_shap_outputs[("SHAP importance")]
end

node_researcher(("Researcher"))
node_adhd200["ADHD-200 source"]

node_adhd200 -->|"provides dataset"| node_raw_csv
node_raw_csv -->|"reads phenotypes"| node_clean_audit
node_clean_audit -->|"writes cleaned data"| node_cleaned_data
node_researcher -->|"runs phase"| node_clean_audit
node_researcher -->|"runs phase"| node_split_preprocess
node_split_preprocess -->|"calls cleaning"| node_clean_audit
node_split_preprocess -->|"writes shared splits"| node_splits
node_splits -->|"supplies rows"| node_model_b_features
node_splits -->|"supplies rows"| node_model_a_features
node_researcher -->|"runs phase"| node_training
node_training -->|"calls preprocessor"| node_model_b_features
node_training -->|"calls preprocessor"| node_model_a_features
node_training -->|"reads train and validation"| node_splits
node_training -->|"writes ensembles"| node_model_artifacts
node_training -->|"writes selection results"| node_selection_reports
node_researcher -->|"runs phase"| node_evaluation
node_evaluation -->|"loads ensembles"| node_model_artifacts
node_evaluation -->|"reads test split"| node_splits
node_evaluation -->|"computes subgroup metrics"| node_fairness
node_evaluation -->|"writes metrics and plots"| node_evaluation_reports
node_evaluation -->|"writes A-versus-B results"| node_comparison
node_researcher -->|"runs secondary check"| node_shap_check
node_shap_check -->|"reads train, validation, test"| node_splits
node_shap_check -->|"calls preprocessor"| node_model_a_features
node_shap_check -->|"writes SHAP results"| node_shap_outputs

click node_raw_csv "https://github.com/aditsawhney/adhd-project/blob/main/data/raw/adhd200_preprocessed_phenotypics.csv"
click node_clean_audit "https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/data.py"
click node_cleaned_data "https://github.com/aditsawhney/adhd-project/blob/main/data/processed/cleaned_full.csv"
click node_split_preprocess "https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/features.py"
click node_splits "https://github.com/aditsawhney/adhd-project/tree/main/data/processed"
click node_model_b_features "https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/features.py"
click node_model_a_features "https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/features.py"
click node_training "https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/train.py"
click node_model_artifacts "https://github.com/aditsawhney/adhd-project/tree/main/models"
click node_selection_reports "https://github.com/aditsawhney/adhd-project/tree/main/reports"
click node_evaluation "https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/evaluate.py"
click node_fairness "https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/evaluate.py"
click node_comparison "https://github.com/aditsawhney/adhd-project/blob/main/reports/comparison_report.csv"
click node_evaluation_reports "https://github.com/aditsawhney/adhd-project/tree/main/reports"
click node_shap_check "https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/shap_analysis.py"
click node_shap_outputs "https://github.com/aditsawhney/adhd-project/tree/main/reports/model_a"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_raw_csv,node_clean_audit,node_cleaned_data,node_split_preprocess,node_splits toneBlue
class node_model_b_features,node_model_a_features,node_training,node_model_artifacts,node_selection_reports toneAmber
class node_evaluation,node_fairness,node_comparison,node_evaluation_reports,node_shap_check,node_shap_outputs toneMint
class node_researcher,node_adhd200 toneIndigo
```

## Components

### Data preparation

- [Raw phenotypes](https://github.com/aditsawhney/adhd-project/blob/main/data/raw/adhd200_preprocessed_phenotypics.csv): `data/raw/adhd200_preprocessed_phenotypics.csv`
- [Clean and audit](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/data.py): `src/neuronova/data.py`
- [Cleaned data](https://github.com/aditsawhney/adhd-project/blob/main/data/processed/cleaned_full.csv): `data/processed/cleaned_full.csv`
- [Split and preprocess](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/features.py): `src/neuronova/features.py`
- [Shared data splits](https://github.com/aditsawhney/adhd-project/tree/main/data/processed): `data/processed`

### Model tracks

- [Pre-assessment features](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/features.py): `src/neuronova/features.py`
- [Extended features](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/features.py): `src/neuronova/features.py`
- [Selection and ensembles](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/train.py): `src/neuronova/train.py`
- [Trained models](https://github.com/aditsawhney/adhd-project/tree/main/models): `models`
- [Selection results](https://github.com/aditsawhney/adhd-project/tree/main/reports): `reports`

### Evaluation and explanation

- [Test evaluation](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/evaluate.py): `src/neuronova/evaluate.py`
- [Sex and age audit](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/evaluate.py): `src/neuronova/evaluate.py`
- [Model comparison](https://github.com/aditsawhney/adhd-project/blob/main/reports/comparison_report.csv): `reports/comparison_report.csv`
- [Metrics and plots](https://github.com/aditsawhney/adhd-project/tree/main/reports): `reports`
- [Standalone SHAP check](https://github.com/aditsawhney/adhd-project/blob/main/src/neuronova/shap_analysis.py): `src/neuronova/shap_analysis.py`
- [SHAP importance](https://github.com/aditsawhney/adhd-project/tree/main/reports/model_a): `reports/model_a`

### Other components

- **Researcher**
- **ADHD-200 source**

## Connections

- ADHD-200 source → Raw phenotypes: provides dataset
- Raw phenotypes → Clean and audit: reads phenotypes
- Clean and audit → Cleaned data: writes cleaned data
- Researcher → Clean and audit: runs phase
- Researcher → Split and preprocess: runs phase
- Split and preprocess → Clean and audit: calls cleaning
- Split and preprocess → Shared data splits: writes shared splits
- Shared data splits → Pre-assessment features: supplies rows
- Shared data splits → Extended features: supplies rows
- Researcher → Selection and ensembles: runs phase
- Selection and ensembles → Pre-assessment features: calls preprocessor
- Selection and ensembles → Extended features: calls preprocessor
- Selection and ensembles → Shared data splits: reads train and validation
- Selection and ensembles → Trained models: writes ensembles
- Selection and ensembles → Selection results: writes selection results
- Researcher → Test evaluation: runs phase
- Test evaluation → Trained models: loads ensembles
- Test evaluation → Shared data splits: reads test split
- Test evaluation → Sex and age audit: computes subgroup metrics
- Test evaluation → Metrics and plots: writes metrics and plots
- Test evaluation → Model comparison: writes A-versus-B results
- Researcher → Standalone SHAP check: runs secondary check
- Standalone SHAP check → Shared data splits: reads train, validation, test
- Standalone SHAP check → Extended features: calls preprocessor
- Standalone SHAP check → SHAP importance: writes SHAP results