HLHS Project

Reproducible HLHS single-nucleus RNA-seq workflow focused on cardiac fibroblast (CF) remodeling, with cardiomyocyte (CM) analyses retained as a secondary comparator/anchor, plus external validation, multicellular-remodeling, and computational drug-reversal outputs.

The root notebook is the single project entrypoint. It mounts Google Drive, resolves local or Colab paths, and runs the external Python scripts in scripts/. The actual analysis code lives under src/hlhs_project/.

Quick Start In Colab

1. Open HLHS Project.ipynb.
2. Run the first path-resolution cell.
3. Confirm DATA_ROOT points to the raw HLHS data folder, usually:

/content/drive/MyDrive/Data/HLHS Data

4. Run the external publication pipeline cell.
5. Review the publication audit cells. They check required outputs and display the readiness report, JACC-gap analysis, external-validation polarity audit, multicellular program summary, and perturbagen reprioritization tables.

Outputs are written to:

outputs/

Command Line

From this folder:

python scripts/run_publication_pipeline.py --data-root "/content/drive/MyDrive/Data/HLHS Data"

Publication-only refresh from cached base outputs:

python scripts/run_publication_pipeline.py --skip-base-pipeline --project-root . --output-dir outputs

Optional online pathway enrichment:

python scripts/run_publication_pipeline.py --online-enrichment

Base pipeline and drug scoring scripts are still available for lower-level reruns:

python scripts/run_hlhs_pipeline.py --data-root "/content/drive/MyDrive/Data/HLHS Data"
python scripts/score_hlhs_drug_reversal.py

Main Outputs

• outputs/differential_expression/: patient-level pseudobulk DE tables.
• outputs/pseudobulk_counts/: patient-level pseudobulk count matrices and sample metadata.
• outputs/signature_gene_sets/: HLHS-up and HLHS-down genes for each cell type and comparison.
• outputs/clue_lincs_inputs/: CLUE/LINCS query files.
• outputs/drug_reversal_results/: automated L1000FWD/LINCS reversal hits, optional imported CLUE or local LINCS scores, and ranked candidates.
• outputs/pathway_enrichment/: optional Enrichr results.
• outputs/figures/: AHA-ready figure panels.
• outputs/tables/: run summaries, design definitions, patient composition, curated program enrichment, validation tables, and figure plan.
• outputs/publication/: manuscript-facing claim gates, primary edgeR tables, external-validation audit, multicellular program storyline, JACC gap analysis, and drug reprioritization outputs.

Current Publication Framing

The current publication artifact set is cardiac-fibroblast-first. The manuscript focus is HLHS cardiac fibroblast stromal/remodeling biology, while preserving cardiomyocyte results as a secondary comparator and the strongest passed gene-level anchor where claim gates support it.

• Primary CF remodeling focus: CF__HF_HLHS_remodeling is the primary signature and should drive the narrative.
• CF gene-level claims: framed cautiously/hypothesis-generating when the CF gene-level gate is blocked.
• CF program-level evidence: used when the program-stability gate passes, without overstating a definitive causal mechanism.
• CM comparator: retained as a secondary comparator/gene-level anchor, not the primary disease focus.
• External validation: supported cautiously in GSE23959 as bulk-tissue calibrated support, not CF-specific validation.
• Multicellular biology: promoted as secondary context through stable endothelial, macrophage, PeriC/SMC, and CM-comparator program summaries where gates support them.
• Perturbagen results: hypothesis-generating only; not therapeutic efficacy.

Key manuscript-facing files:

• outputs/publication/publication_readiness_report.md
• outputs/publication/jacc_gap_analysis.md
• outputs/publication/manuscript_claim_language_guide.csv
• outputs/publication/multicellular_storyline.md
• outputs/publication/external_validation_polarity_audit.csv
• outputs/publication/gse23959_signature_direction_plot.svg
• outputs/publication/drug_candidate_journal_reprioritization.csv