# ๐ง ASD_Seeker
**Clinical decision-support for autism (ASD), over a public brain-imaging reference space.**
It compares one person's brain-network features to a **Normal** reference, shows how and
where they differ, and how confident the read is โ as an adjunct to a clinician's judgement.
[**๐ 1-page summary**](clinic/index.html) ยท [**๐ฌ In-depth analysis**](braintwin/index.html) ยท [How it works](#-what-it-does) ยท [Run it](#-run-it-in-10-seconds) ยท [How it's built](docs/ARCHITECTURE.md)
> โ ๏ธ **Decision-support only โ NOT FDA-cleared, NOT for stand-alone diagnosis.**
> An adjunctive reference. Use together with behavioral assessment (ADOS, SRS),
> developmental history, and specialist judgement. See [docs/DISCLAIMER.md](docs/DISCLAIMER.md).
---
## ๐ What it does
```mermaid
flowchart LR
A["๐ง Public brain-MRI
ABIDE I ยท ADHD-200"] --> B["Extract brain-network
connectivity features"]
B --> C["Compare to a
NORMAL reference brain"]
C --> D["How different?
which networks stand out?"]
D --> E["๐ 1-page summary
๐ฌ in-depth view"]
E --> F["๐ฉบ Clinician decides
imaging is one clue,
not a diagnosis"]
style C fill:#e0f2f1,stroke:#0f766e
style F fill:#eef2ff,stroke:#4f46e5
```
A single subject's resting-state brain features are projected into a reference space built
from a **Normal (control)** cohort. The app answers three plain questions: *how far from
typical is this brain?*, *which networks drive the difference?*, and *how sure are we?* It
never returns a diagnosis โ behavioral assessment stays the clinical standard.
## ๐จ How to read a result
```mermaid
flowchart TD
S["This subject's brain pattern"] --> Z{"Where on the
Normal โ ASD scale?"}
Z -->|"๐ต toward Normal"| N["Normal-leaning
does NOT rule out autism"]
Z -->|"โช inconclusive middle"| U["Defer the call โ
rely on behavioral assessment"]
Z -->|"๐ด toward ASD"| R["ASD-leaning โ
a statistical signal,
NOT a diagnosis"]
N --> B["โ
Behavioral assessment is the standard
ADOS ยท SRS ยท developmental history"]
U --> B
R --> B
style N fill:#eff6ff,stroke:#1d4ed8
style R fill:#fef2f2,stroke:#dc2626
style B fill:#f0fdf4,stroke:#16a34a
```
**Colors are consistent everywhere and clinically load-bearing:**
๐ด **warm / red = ASD-leaning** (higher / excess) ยท ๐ต **cool / blue = Normal-leaning**
(lower / deficit) ยท deeper color = larger deviation.
## โถ Run it in 10 seconds
> **No install, no build, no server.** It is a static web app that runs offline.
**Option 1 โ just open it (easiest):**
1. Download the repo (green **Code โ Download ZIP**, or `git clone`).
2. Double-click **`index.html`**. It opens in your browser. Done.
**Option 2 โ local server (optional, for developers):**
```bash
python -m http.server 8000
# then open http://localhost:8000/
```
The in-depth view ships **40 subjects fully inlined**, so every listed subject opens with no
network calls. (`three.js` loads from a CDN for the 3D brain; everything else is local.)
## ๐ฅ๏ธ What's inside โ two views
| View | Folder | For | What you see |
|---|---|---|---|
| **๐ 1-page summary** | `clinic/` | quick triage | verdict band (Normal โ ASD), recommended next step, behavior-first anchor. Covers all **1257** subjects from one bundle. |
| **๐ฌ In-depth analysis** | `braintwin/` | deeper read | 7 tabs: functional-network deviation map, 3D brain, age/sex norms, cortical surface, evidence markers, model facts. Each tab opens with a plain-language **clinical lens**. |
The two views **share the selected subject** (via `localStorage`), so you can jump between
the quick read and the deep dive on the same person.
## โ๏ธ How it's built
```mermaid
flowchart LR
subgraph SRC["Public datasets"]
A1["ABIDE I ยท PCP
C-PAC ยท CC200 ยท 200-ROI"]
A2["ADHD-200"]
end
SRC --> P["pipeline/
feature extraction +
reference fit + normative model"]
P --> D1["braintwin_data.js"]
P --> D2["clinic_data.js"]
P --> D3["subjects_inline.js"]
D1 --> W["Static web app
clinic/ + braintwin/"]
D2 --> W
D3 --> W
style P fill:#e0f2f1,stroke:#0f766e
style W fill:#eef2ff,stroke:#4f46e5
```
Full architecture, data-flow, and schema diagrams: **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
## ๐ Honest performance
| Number | What it is |
|---|---|
| **AUROC 0.91** | Internal validated model โ **public release pending**. The headline target; its data/weights are **not in this repo**, and the live demo does **not** use it. |
| **AUROC 0.626** | The model this demo actually runs: ABIDE I, leave-one-site-out (honest cross-site). Per-site AUC ranges **0.31โ0.73** across 20 sites. |
| **AUROC 0.743** | Clinic pooled 5-fold (in-sample, optimistic vs leave-one-site-out). |
> **Leakage guard:** any pooled cross-site AUC above ~0.78 on ABIDE is a red flag. The
> deployed honest number is **0.626 LOSO**.
## ๐๏ธ Dataset (sample only)
- **ABIDE I PCP** โ C-PAC, CC200 atlas (200 ROI), strict-QC **n = 937** (ASD 424 / Normal
513), 20 sites, mean framewise displacement โค 0.20.
- The 1-page view covers **1257** = 937 strict-QC + 165 relaxed-QC ABIDE + 155 ADHD-200,
projected through the strict reference.
- **This repo ships a SAMPLE**, not the full data: the clinic bundle holds all 1257 in one
file; the in-depth view ships a **40-subject offline sample**. The full 213 MB per-subject
library and 4.2 GB of raw data are **not redistributed**. See [DATA.md](DATA.md).
## ๐ Repository layout
```
.
โโโ index.html Landing page (entry to both views + diagrams)
โโโ clinic/ 1-page summary (self-contained, all 1257)
โ โโโ index.html ยท app.js ยท style.css
โ โโโ clinic_data.js all 1257 subjects, single bundle
โ โโโ lib/plotly.min.js vendored (offline)
โโโ braintwin/ In-depth analysis (self-contained SPA)
โ โโโ index.html ยท css/ ยท js/
โ โโโ data/
โ โโโ braintwin_data.js meshes + reference + 16 subjects (inline)
โ โโโ subjects_inline.js 24 more subjects (inline โ offline)
โ โโโ subject_index.js light index of the 40 sampled subjects
โ โโโ dss_data.js decision-support pack
โโโ pipeline/ Reproducibility source (Python package + build scripts)
โโโ docs/ ARCHITECTURE ยท DATA_SCHEMA ยท REPRODUCIBILITY ยท DISCLAIMER
โโโ tools/assemble.sh Re-buildable: regenerates this repo from the research tree
```
## ๐ Reproduce the full data
Web artifacts regenerate from the public datasets with `pipeline/` (you supply ABIDE/ADHD
under their terms). See **[docs/REPRODUCIBILITY.md](docs/REPRODUCIBILITY.md)**.
## ๐ License ยท Data ยท Disclaimer
- **Code:** Apache-2.0 ([LICENSE](LICENSE)).
- **Data:** ABIDE and ADHD-200 carry their own terms; this repo redistributes only
**derived, de-identified features**. See [DATA.md](DATA.md).
- **Clinical:** research / decision-support only. **Not a medical device. Not for
stand-alone diagnosis.** See [docs/DISCLAIMER.md](docs/DISCLAIMER.md).