BioForge · NeuralTF

A reproducible pipeline for planarian neural-fate-specific transcription factor discovery. Integrates five single-cell and regulatory atlases (Fincher 2018, Plass 2018, Cui 2023, King 2024, Perez 2025) — including the previously unused Fincher brain sub-atlas and the Cui regeneration time-course — into 11 evidence streams, with Bayesian Dirichlet uncertainty quantification, a cross-species ortholog benchmark, and ANANSE gene regulatory network validation to prioritize high-confidence targets for RNAi and functional validation.

---

Quick Start

# 1. Set up Python 3.12+ environment
git clone https://github.com/dhzso/neuraltf.git
cd neuraltf

python -m venv .venv
.venv\Scripts\activate                       # Windows
# source .venv/bin/activate                  # Linux/Mac

pip install -e ".[bio,streamlit]"

# 2. Place raw downloads in datasets/raw/ (see datasets/MANIFEST.md)
#    and build all processed artifacts with ONE master orchestrator:
python scripts/generate_all.py

# 3. Or run the pipeline and downstream analyses step-by-step:
python scripts/run.py                        # Core pipeline (Fincher, Plass, Cui, King, Perez)
python scripts/run_downstream.py             # Dirichlet UQ, ANANSE scan, tables & 32 figures

# 4. Launch the interactive Streamlit UI
bioforge ui                                  # http://localhost:8501

Pipeline Outputs (projects/NeuralTF/runs/pipeline_run/)

File	Content
rank.csv	All 11,696 candidates with scores across all 11 evidence streams + phenotype_confirmed ground-truth flag
rank_neural.csv	Neural-enriched candidates with proof status + ground_truth_status
evidence_cards.md	Per-candidate markdown evidence summary
pipeline_results.json	Machine-readable candidate metadata
de_pvalues.parquet	Per-gene best DE p per atlas (meta-analysis input)
checkpoint_0*.parquet	6 incremental checkpoints (atlas loads, post-QC, post-scoring, King, Perez, stream matrix)

Prioritization & Analysis Outputs (projects/NeuralTF/results/)

File	Content
master_tf_catalog.csv	Unified King + Perez TF catalog (14,682 unique v6 TFs) — in projects/NeuralTF/data/
dirichlet_centered_full_rank.csv	Full Dirichlet-centered (k=40) composite rank (all candidates, 1 row/gene)
dirichlet_uniform_full_rank.csv	Full Dirichlet-uniform (α=1) composite rank (all candidates, 1 row/gene)
dirichlet_centered_top10.csv	Dual-track top-10 shortlist under centered Dirichlet (5 RNA-screened + 5 Unscreened)
dirichlet_uniform_top10.csv	Dual-track top-10 shortlist under uniform Dirichlet (5 RNA-screened + 5 Unscreened)
dirichlet_*_draw_scores.csv	Per-candidate draw-score matrices (bootstrap CIs, convergence)
ananse_network_full.csv	ANANSE GRN scan across all candidates & 9 cell fates (RBH-mapped, neuron-share normalized)
ananse_top_regulators.csv	Top planarian neural regulators (neuron-fate out-degree first)
tf_ranked_neural_top19.csv	Top 19 TFs: neural-filtered candidates
tf_ranked_all_top43.csv	Top 43 TFs: all expression-filtered candidates
tf_ranked_catalog_top74.csv	Top 74 TFs: full King mmc4 catalog
supplementary_table_S1 – S7	Method comparison, and fixed/centered/uniform rank tables across all candidates
de_pvalues.parquet	Per-gene best DE p per atlas (pipeline checkpoint; drives meta-analysis)

---

What It Does

The pipeline seeds candidate TFs across five single-cell and regulatory atlases, computes an 11-stream multi-evidence matrix, evaluates scoring stability under Dirichlet uncertainty sampling, and maps candidates into cell-fate regulatory circuits.

Atlases Integrated (5)

Atlas	Year	Modality / Data Type	Role in Pipeline
Fincher	2018	scRNA-seq (50.5K cells, v4 IDs)	Whole-animal cell-type expression & neural specificity (GSE111764)
Plass	2018	scRNA-seq (37.5K cells, v6 IDs)	Independent whole-anatomy replication & X1 dynamics (GSE103633)
Cui	2023	scRNA-seq (55.0K cells, 8 time points)	High-resolution regeneration time-course expression (OMIX)
King	2024	Single-cell TF catalog + RNAi screen	G0/X1 cluster enrichment, RNAi phenotypes (mmc5), TF pair correlations (mmc6) (Cell Reports)
Perez	2025	Lineage atlas + ANANSE GRNs	Lineage TF classification (MOESM5), ANANSE regulatory influence (MOESM19), and ANANSE GRN (MOESM22) (Nature Communications)

---

Evidence Streams & Scoring Model (11 Streams)

Scoring utilizes a transparent, weighted multi-evidence integration model. Weights renormalize over streams present for each candidate:

$$\text{Integrated Score} = \sum_{i \in \text{Present}} w_i \cdot s_i \Bigg/ \sum_{i \in \text{Present}} w_i$$

#	Stream	Default Weight ($w_i$)	Biological Basis & Computation
1	Expression	0.100	$\min(1.0, \max(\text{log}_2\text{FC})/5)$ across Fincher, Plass, Cui, and King scRNA-seq atlases
2	Specificity	0.100	$1 / n_{\text{clusters}}$ supporting differential expression
3	Reproducibility	0.100	$n_{\text{atlases supporting}} / 5$ (Fincher, Plass, Cui, King, Perez)
4	RNAi	0.050	Binary indicator (1.0) if the TF was RNAi-screened with markers assayed in King mmc5 ("All Transcription Factors Inhibited") — screened, phenotype NOT implied
5	Correlation	0.050	$\min(1.0, \Delta r_{\text{G0-X1}} \times 3.0)$ co-expression gain from King mmc6
6	Neural Enriched	0.100	Binary indicator (1.0) for G0 neural subcluster log₂FC ≥ 1.5 (King mmc7)
7	Neural Specificity	0.100	$1 / n_{\text{neural subclusters}}$ present in King atlas
8	Perez Lineage	0.100	Perez 2025 lineage TF class: 1.0 for neural-class, 0.5 for other TF classes, 0.0 if absent
9	Perez Influence	0.100	Perez 2025 ANANSE regulatory influence in neuron fate (MOESM19), normalized 0–1 rank
10	Fincher Brain	0.100	Independent Fincher 2018 BrainClustering sub-atlas enrichment ($\min(1.0, \text{log}_2\text{FC}/5)$ over brain Leiden clusters)
11	Cui Temporal	0.100	Cui 2023 regeneration time-course: neuronal temporal induction $\min(1.0, \log_2(\text{peak}/\text{baseline})/2)$ over the 8 timepoints

Confidence Tiers & Proof Status

• Tier Assignment:
  • HIGH: RNAi-screened OR (supporting streams ≥ 3 AND score ≥ 0.45)
  • MEDIUM: supporting streams ≥ 2 AND score ≥ 0.25
  • LOW: All other candidates

---

Top Prioritized Candidates (Production Run — Full Atlases, 11,696 Candidates)

Consensus across all three unified methods (fixed / centered Dirichlet k=40 / uniform Dirichlet α=1; shared universe, bonus mask, and gates) under the 11-stream model. All three methods emit identical top-10 shortlists (10/10 consensus) — by design the methods share most streams, so this consensus measures weight-robustness, not method independence (see overlap_significance.json caveat; the stratification-corrected null is reported alongside the legacy upper bound).

Testing status	Consensus candidates	Evidence
Tested #1	dd_Smed_v6_38342_0_1 (dd38342 / POU3F4-class)	RNAi-screened (†); consistent top-1 across methods
Tested #2	dd_Smed_v6_34144_0_1 (dd34144 / TCF7-LEF)	RNAi-screened (†)
Tested #3	dd_Smed_v6_12722_0_1 (dd12722 / BHLHE23)	RNAi-screened (†)
Tested #4	dd_Smed_v6_29211_0_1 (dd29211 / PHOX2A)	RNAi-screened (†); FISH phenotype-confirmed (dd8060+ neuron loss)
Tested #5	dd_Smed_v6_22163_0_1 (dd22163 / UNCX)	RNAi-screened (†); FISH phenotype-confirmed (sert+ neuron loss)
Not tested #1	dd_Smed_v6_33456_0_1 (dd33456)	Homeodomain; consensus top not-tested
Not tested #2	dd_Smed_v6_18505_0_1 (dd18505 / MSH1)	Homeodomain (msh1)
Not tested #3	dd_Smed_v6_16466_0_1 (dd16466 / FOXG1)	Forkhead; oral/neural forebrain ortholog
Not tested #4	dd_Smed_v6_2442_0_1 (dd2442 / HOXC6)	Homeobox
Not tested #5	dd_Smed_v6_13704_0_1 (dd13704 / PTF-4)	bHLH

Per-method shortlists: dirichlet_centered_top10.csv, dirichlet_uniform_top10.csv, top10_neural_tfs_prioritized.csv (all carry phenotype_confirmed).

Ground-truth recovery under the 11-stream model (both labels, circularity-controlled — label-encoding streams excluded): screened label (68 genes): honest ROC-AUC 0.866, strict 0.819, king-free 0.819, vs 0.978 circular; phenotype_confirmed label (19 in-universe genes): honest ROC-AUC 0.944, strict 0.891, king-free 0.891. The king_free arm excludes every stream drawing on King 2024 — the study that also defines the labels — quantifying how much discrimination the independent atlases (Fincher, Plass, Cui, Perez-influence, Fincher-brain) provide alone; residual caveat: expression/specificity still carry King-mmc7 floors fused at pipeline time, so even king_free is an upper bound. An independent cross-species ortholog benchmark (neural-fate vs non-neural human orthologs, honest label-free score) gives ROC-AUC 0.634 (95% CI 0.52–0.74, one-sided Mann-Whitney p=0.011; the full circular score reads 0.712 and mostly measures label re-encoding). Provisional, coverage-limited (~101 genes).

Known limitations

1. "Tested" = screened. 48 of 68 screened TFs have no published phenotype; only 20 genes are FISH phenotype-confirmed (bioforge.evidence.groundtruth). All "validated" claims must use the phenotype_confirmed flag.
2. Recall is imperfect. dd_Smed_v6_48508_0_1 has a confirmed neuron-loss phenotype but never entered the candidate universe (no seeded evidence) — the funnel misses it.
3. Cross-method consensus is not independence. The three methods share 9 of 11 streams, the bonus mask, and the King floors; the overlap p-values are an upper bound on significance, and both the legacy uniform-subset null and the stratification-corrected (dual-track 5+5) null are reported in overlap_significance.json.
4. fincher_brain presence, not value, carries most of its signal. Its unconditional per-stream AUC (~0.41 against the screened label) is a missingness artifact: among genes where the stream is present, the value-only AUC is ~0.66. The per-stream table in precision_recall.json reports both variants.
5. King-derived expression still enters the honest score. The honest/strict AUCs exclude label-encoding streams but keep King mmc7 expression floors; they are an upper bound on true label-free discrimination. The king_free arm removes the pure King streams but cannot un-fuse the King floors — see precision_recall.json.
6. Ortholog benchmark is provisional (~101 classified genes from PlanMine BLAST descriptions; a full Compara/DIOPT table is needed for a definitive benchmark). The honest-score AUC (0.634) carries a wide CI (0.52–0.74) at this coverage.

---

Uncertainty Quantification & Sensitivity (Dirichlet Sampling)

To test sensitivity against arbitrary weighting assumptions, we employ Monte Carlo Dirichlet weight perturbation (1,000 draws, seed=2024 across all candidates in rank.csv):

1. Centered Dirichlet ($k = 40$): $$\mathbf{w}^{(m)} \sim \text{Dirichlet}(k \cdot \mathbf{w}_{\text{default}})$$ Perturbs weights locally around default parameters ($\sim 95%$ of draws within $\pm 0.10$ of baseline).

   • python projects/NeuralTF/scripts/dirichlet_centered.py

2. Uniform Dirichlet ($\alpha_i = 1$): $$\mathbf{w}^{(m)} \sim \text{Dirichlet}(\mathbf{1}_{11})$$ Samples uniformly across the entire 11-simplex to discover robust data-driven signals without prior preference.

   • python projects/NeuralTF/scripts/dirichlet_uniform.py

---

Statistical Validation Suite (15 Tests)

The pipeline includes a comprehensive statistical validation suite to ensure publication-grade rigor:

#	Test	Script	Key Metrics
1	Full Permutation Test	scripts/stats/permutation_test_full.py	Empirical p-values (n=1,000 permutations)
2	Bootstrap Confidence Intervals	scripts/stats/bootstrap_confidence.py	95% CI on integrated scores
3	Overlap Significance	scripts/stats/overlap_significance.py	Hypergeometric, Fisher's exact, binomial tests
4	Precision-Recall Analysis	scripts/stats/precision_recall.py	Precision@5, Precision@10, PR-AUC
5	Negative Controls	scripts/stats/negative_controls.py	Random non-TF & non-neural TF distributions
6	Effect Sizes	scripts/stats/effect_sizes.py	Cliff's delta, Cohen's d, Mann-Whitney U
7	Leave-One-Atlas-Out	scripts/stats/leave_one_atlas_out.py	Top-10 stability per excluded atlas
8	Meta-Analytic P-values	scripts/stats/meta_analytic_pvalue.py	Fisher's & Stouffer's combined p-values
9	Power Analysis	scripts/stats/power_analysis.py	Convergence & power curves
10	Mann-Whitney U (Top-10)	scripts/stats/mann_whitney_top10.py	Rank-biserial correlation
11	Calibration Analysis	scripts/stats/calibration.py	Empirical positive rates per decile
12	Brier Score	scripts/stats/brier_score.py	Probabilistic classification accuracy
13	Cross-Method Correction	scripts/stats/cross_method_correction.py	Bonferroni/BH-FDR for 3-method consensus
14	Score Shuffling Permutation	scripts/stats/score_shuffling_permutation.py	Stream-assignment null model
15	Cross-Species Ortholog Benchmark	scripts/stats/ortholog_benchmark.py	Conserved H. sapiens neural TF ROC-AUC (0.634 honest label-free) & Mann-Whitney test

Run all tests:

python scripts/run_statistical_tests.py

---

Repository Structure

Bioinformatics/
├── pyproject.toml                            Package configuration & dependencies
├── README.md                                 Primary documentation
├── bioforge.md                               BioForge framework reference & operations
│
├── src/bioforge/                             BioForge Core Framework
│   ├── evidence/                             Multi-stream evidence engine
│   │   ├── schema.py                        EvidenceRecord & 11-stream EvidenceSource enum
│   │   ├── scoring.py                       Weighted score integration & DEFAULT_WEIGHTS
│   │   ├── confidence.py                    Tier classification (HIGH/MEDIUM/LOW)
│   │   ├── groundtruth.py                   King-2024 ground truth: screened vs phenotype-confirmed labels
│   │   └── cards.py                         Markdown evidence card generation
│   ├── projects/neuraltf/
│   │   ├── pipeline.py                       NeuralTFPipeline (5-atlas loader & 6 checkpoints)
│   │   ├── planmine.py                       PlanMine InterMine REST client & annotation parser
│   │   └── prioritize.py                     Dual-track candidate scoring & filtering
│   ├── omics/                                scRNA-seq QC, log-norm, PCA, Leiden clustering
│   ├── workflow/                             Declarative YAML workflow engine
│   ├── cli/                                  Command-line interface
│   └── ui/                                   Streamlit interactive dashboard
│
├── datasets/
│   ├── MANIFEST.md                           Download URLs & SHA256 checksums
│   ├── raw_data_manifest.md                  Complete 27-file raw data inventory
│   ├── raw/                                  Raw downloads (gitignored)
│   └── processed/                            Processed H5ADs & Parquet files (gitignored)
│
├── projects/NeuralTF/
│   ├── data/
│   │   ├── bridge.csv                        v4 ↔ v6 ↔ gene_name Rosetta Stone mapping
│   │   ├── king_atlas.tsv                    King 2024 G0 progenitor enrichment table
│   │   ├── perez_tf_summary.csv              Perez 2025 TF lineage classification
│   │   └── master_tf_catalog.csv             Unified King + Perez master TF catalog (14,682 TFs)
│   ├── scripts/
│   │   ├── convert_cui.py                    Cui SMED → v6 H5AD (optional --subsample N)
│   │   ├── preprocess_perez.py               Parse Perez MOESM5 TF classes
│   │   ├── annotate_phenotype_groundtruth.py  Stamp phenotype_confirmed on all outputs (idempotent)
│   │   ├── dirichlet_centered.py             Centered Dirichlet k=40 (all candidates)
│   │   ├── dirichlet_uniform.py              Uniform Dirichlet α=1 (all candidates)
│   │   ├── ananse_full_scan.py               ANANSE GRN scan across all candidates
│   │   ├── export_fstf_ranked.py             Export ranked TF tables
│   │   ├── create_supplementary_tables.py    Generate supplementary tables S1–S4
│   │   ├── generate_publication_figures.py   Generate 32 publication figures
│   │   └── figures/                          32 modular figure generation scripts & style.py
│   ├── results/                              Dirichlet, ANANSE, and supplementary tables (gitignored)
│   ├── figures/                              32 publication + 4 supplementary PNG figures (gitignored)
│   └── runs/pipeline_run/                    rank.csv, rank_neural.csv, 6 checkpoint parquets
│
└── scripts/                                  Master Orchestration & Build Scripts
    ├── generate_all.py                       End-to-end multi-step master pipeline runner
    ├── run_downstream.py                     Post-pipeline runner (Dirichlet, ANANSE, figures, stats)
    ├── run_statistical_tests.py              Run all 15 statistical tests
    ├── run.py                                Core pipeline execution entry point
    ├── build_bridge.py                       Build v4↔v6 gene ID bridge from Rosetta Stone
    ├── build_king_atlas.py                   Build king_atlas.tsv from King mmc7
    ├── build_master_catalog.py               Merge King mmc4 + Perez MOESM5 TF catalog
    ├── convert_fincher.py                    Convert Fincher DGE to H5AD
    ├── consolidate_plass.py                  Consolidate Plass RAW.tar to H5AD
    └── stats/                                15 statistical test scripts
        ├── permutation_test_full.py
        ├── bootstrap_confidence.py
        ├── overlap_significance.py
        ├── precision_recall.py
        ├── negative_controls.py
        ├── effect_sizes.py
        ├── leave_one_atlas_out.py
        ├── meta_analytic_pvalue.py
        ├── power_analysis.py
        ├── mann_whitney_top10.py
        ├── calibration.py
        ├── brier_score.py
        ├── cross_method_correction.py
        ├── score_shuffling_permutation.py
        └── ortholog_benchmark.py

---

License

MIT — see LICENSE file.