Immune-Causal-Atlas

jianlizhao/Immune-Causal-Atlas

Immune-Causal-Atlas is a machine learning model from jianlizhao. Use it for the machine learning task on the model card, and read the license before you ship it in a product.

A phenome-wide, colocalization-aware immune causal atlas linking genetically regulated immune-cell states (731 immunophenotypes, Orrù 2020) to the circulating inflammatory secretome (91 Olink proteins, Zhao 2023), map…

Downloads · 30 days

Access

Public

Updated Sep 23, 2026

Repo size

—

Likes

Public

Hugging Face

Repo makeup

Click a slice to open those files.

.json1.5 MB · 82%

At a glance

Access: Public
Created: Sep 23, 2026
Updated: Sep 23, 2026
SHA: cdf12ec7

Model card

From the Hugging Face model README

Immune Causal Atlas (ICA)

A phenome-wide, colocalization-aware immune causal atlas linking genetically regulated immune-cell states (731 immunophenotypes, Orrù 2020) to the circulating inflammatory secretome (91 Olink proteins, Zhao 2023), mapped across the FinnGen disease-ome, with therapeutic causality separated from prospective diagnostic utility.

Strict implementation of Immune_Causal_Atlas_Blueprint.md v1.0 (2026-09-22).

G  →  C (immune-cell state)  →  P (secreted protein)  →  D (disease)

Core design principle (§37): association ≠ causality ≠ predictive utility ≠ therapeutic tractability — four statements, four independent evidence streams, one system.

Key numbers (§3)

Grid	Tests
Cell → protein (forward)	731 × 91 = 66,521
Bidirectional cell ↔ protein	133,042
822 exposures × FinnGen endpoints	~2.26 M
Mediation triplets	gated only — never the brute-force 183 M

Pipeline (§34 order)

Step	Script	Blueprint
1. Freeze manifest	`scripts/00_build_manifest.py`	§29
2. Download all layers	`scripts/01_download.py`	§2
3. Instrument library (Tier A/B, F>10, clump r²<0.001/10Mb)	`scripts/03_instruments.py`	§5
4. Stage 1 bidirectional MR (IVW, Egger, W-median, W-mode, PRESSO, LOO, Steiger)	`scripts/04_stage1.py`	§6–7, §9
5. Colocalization (ABF + multi-signal)	`scripts/05_coloc.py`	§8
6. Stage 2 phenome fast screen (two-pass)	`scripts/06_stage2.py`	§10, §28.5
7. Targeted reverse MR	`scripts/07_reverse_mr.py`	§10.2
8. Mediation + MVMR	`scripts/08_mediation_mvmr.py`	§11–12
9. Aggregate: gates, FDR, 2×2, modules, novelty, tiers, figures	`scripts/10_aggregate_atlas.py`	§13–24

Or: python scripts/run_all.py [--quick] [--online]

Dashboard: run app.bat → live download/analysis viewer at http://localhost:8731/viewer/.

Data layers (§2)

Immune cells: GCST90001391–GCST90002121 (N=3,757 Sardinians; GRCh38 harmonised files preferred).
Proteins: GCST90274758–GCST90274848 (N=14,824; Olink Inflammation; 59 cis + 121 trans pQTLs).
Disease-ome: FinnGen R11 public summary stats (2,440 endpoints). Blueprint cites DF13; R11 is the openly downloadable bucket as of 2026-09, and endpoint definitions are cross-referenced to the R13 browser.
Phase-2 layers (connectors, access-controlled or on-demand): UKB-PPP 2,923-protein pQTLs, eQTL Catalogue/GTEx, Open Targets, ChEMBL.

Statistical guarantees

Hierarchical family→within-family BH-FDR (§9.2/§10.1); global Bonferroni columns retained as audit flags (7.52e-7 stage 1; 2.21e-8 stage 2).
PASS_MAIN gate (§24): q<0.05 ∧ instruments ∧ direction ∧ Steiger ∧ no-pleiotropy ∧ PP4≥0.80 ∧ replication.
MR + low PP4 ⇒ MR-only / genetically ambiguous — never promoted to "diagnostic biomarker" (§8.3). E_B requires measured pre-diagnostic data; synthetic runs are hard-labeled SYNTHETIC_DEMO (§33).
Negative-control endpoints, HLA leave-out, winner's-curse and sample-overlap flags (§25).

Outputs

The 17 reproducible tables of §35 in tables/ (each stamped with software version, parameter hash, data-release ID), figures of §23 in figures/, run report in reports/.

Repository layout

Blueprint §27.1 directory architecture; engine code in ica/; orchestration in scripts/; live dashboard in viewer/ + app.bat.

License / citation

Code: MIT. Data: respect the licenses/terms of GWAS Catalog, FinnGen, Open Targets, ChEMBL. Cite Orrù 2020 (Nat Genet), Zhao 2023 (Nat Immunol), FinnGen, and this repository.

Created: Sep 23, 2026
Updated: Sep 23, 2026