Garcia Lab HLHS Single-Cell Analysis

Real-analysis pipeline for the Garcia Lab HLHS dataset, built for Google Colab with a thin notebook runner and reusable src/ modules. The primary biological contrast is disease_status (HLHS vs Control), represented for the project goal as sv_status (SV_HLHS vs non_SV_control). palliation_stage is evaluated only within SV/HLHS samples.

Primary Project Goal

The Garcia Lab project is designed to determine whether T-cell subtype composition and relative subtype percentages differ between SV/HLHS patients and controls, and whether T-cell subtype profiles vary across palliation stages within the SV/HLHS cohort (Pre-Norwood, Pre-Glenn, Pre-Fontan, Post-Fontan, Failing SV).

Important framing: this dataset does not include a non-SV CHD comparator group. SV status is aliased with HLHS/control status, so results must not be described as SV-CHD vs non-SV-CHD. T-cell subtype proportions are within-T-cell percentages per sample; unresolved Unknown and Ambiguous T-cell categories are retained and shown, while non-T sentinels are excluded from subtype denominators.

Data

Expected Google Drive location: Data/Garcia Lab Data/.

File	Role
HLHS_WT_Trailmaker.h5ad	Primary WT expression AnnData used for expression, annotation, composition, and exploratory expression-shift triage. Contains X matrix, UMAP, Leiden, Harmony, samples, GROUP, and TCR Detected.
HLHS_Immune_Trailmaker.h5ad	Immune/TCR companion AnnData for clonotype/TCR metadata summaries. It is not the primary expression object.
Parse TCR Mega_Metadata.xlsx	Clinical/sample metadata workbook. Joined by expression/TCR obs['samples'] to workbook ID; metadata coverage below the configured threshold is a hard stop.
data_processing_settings.txt	Trailmaker processing settings copied into outputs for provenance.

Previously generated outputs from the old immune/TCR-primary run should be treated as stale. Re-run the notebook to regenerate outputs/ from the real WT expression object.

Quick Start

1. Open Garcia_Lab.ipynb in Google Colab.
2. Run the Drive mount cell and complete Google authorization when prompted.
3. Run the dependency install cell. If Colab upgrades core packages, restart the runtime and rerun the notebook from the top before starting analysis.
4. Run all remaining cells. The notebook adds src/ to sys.path and calls run_pipeline(run_tcell_subtyping=True).
5. Review outputs/garcia_lab_summary_report.md plus CSVs under outputs/tables/ and outputs/de_results/.

Pipeline Stages

Stage	Module	Outputs
0	src/data_io.py	Dataset identity, obs audit, metadata coverage hard gate, group counts, sample counts, Trailmaker settings, TCR companion identity.
1	src/annotation.py	Marker availability, marker diagnostics, putative cluster labels, annotation composition by sample.
2	src/composition.py	Sample x broad cell-type counts/proportions, within-T-cell subtype proportions, sample-level subtype summaries/tests, pooled broad group composition with caveats.
3	src/differential.py	Guarded exploratory expression-shift/variance triage on eligible clusters using sample-level means. Cell-level Wilcoxon ranking is off unless explicitly enabled.
4	src/tcr_analysis.py	Expression-level TCR detection summaries and companion clonotype/diversity summaries.
5	src/summary.py	Honest markdown report assembled from available CSV artifacts.

Key Outputs

Path	Description
outputs/garcia_lab_summary_report.md	Main narrative report with caveats and next steps.
outputs/tables/data_audit_dataset_identity.csv	One-row identity for expression/TCR/metadata inputs and selected columns.
outputs/tables/data_audit_sample_metadata_coverage.csv	Sample-level metadata join coverage.
outputs/tables/data_audit_group_counts.csv	Cell/sample counts for analysis_group, GROUP, metadata group, and disease_status.
outputs/tables/cell_type_marker_availability_summary.csv	Marker availability by putative cell type.
outputs/tables/cell_type_annotations.csv	Cluster to putative cell-type assignments.
outputs/tables/tcell_subtype_marker_availability.csv	Marker availability and resolvable/unresolvable status for T-cell subtype panels.
outputs/tables/tcell_subtype_annotations.csv	Cluster-level conservative T-cell subtype annotations.
outputs/tables/tcell_subtype_proportions_by_sample.csv	Within-T-cell subtype proportions by sample; includes Unknown and Ambiguous T-cell categories.
outputs/tables/tcell_subtype_sample_level_summary.csv	Group summaries of within-T-cell subtype proportions for SV/control and within-SV palliation stages.
outputs/tables/tcell_subtype_sample_level_tests_sv_status.csv	Exploratory sample-level SV/HLHS vs control subtype tests with pval and qval.
outputs/tables/tcell_subtype_sample_level_tests_palliation_stage.csv	Exploratory within-SV palliation-stage subtype tests with controls/Unknown excluded.
outputs/tables/sample_cell_type_counts.csv	Sample-level cell-type counts.
outputs/tables/sample_cell_type_proportions.csv	Sample-level cell-type proportions.
outputs/tables/composition_sample_level_summary.csv	Group summaries of sample-level cell-type proportions.
outputs/tables/composition_sample_level_tests_all.csv	Exploratory sample-level composition tests.
outputs/de_results/exploratory_pseudobulk_expression_shift_variance_*.csv	Exploratory expression-shift/variance triage ranking tables. Adjusted p-values are ranking aids only.
outputs/de_results/pseudobulk_expression_shift_variance_diagnostics.csv	Triage comparison/eligibility diagnostics.
outputs/tables/tcr_detection_by_sample.csv	TCR-detected fraction from expression obs.
outputs/tables/tcr_clonotype_summary_by_sample.csv	Companion TCR clonotype/diversity summary by sample.

Guardrails

• Use samples as the biological sample key. Do not use orig.ident for this dataset because it is a single UUID-like value.
• Use disease_status as the primary HLHS vs Control contrast and sv_status as its explicit study-goal alias (SV_HLHS vs non_SV_control). Do not claim SV-CHD vs non-SV-CHD comparisons.
• Use palliation_stage only for within-SV/HLHS comparisons; controls and Unknown stages are excluded from palliation-stage tests.
• Cell-type labels are putative marker-score labels, not manual expert annotation.
• T-cell subtype labels are conservative marker-panel calls. Panels with too few available markers are unresolvable, weak cells remain Unknown, and close top scores remain Ambiguous.
• T-cell subtype percentages are within-T-cell percentages per sample; Unknown and Ambiguous are included as unresolved T-cell categories, while Non-T cell and Unknown non-T are excluded from the denominator.
• Pooled single-cell chi-square summaries and optional cell-level Wilcoxon ranking are exploratory because cells are not independent biological replicates.
• Pseudobulk outputs are exploratory expression-shift/variance triage using guarded sample-level mean expression and limited gene/cluster defaults. They are not formal differential expression.
• Formal differential expression requires count-based pseudobulk modeling with edgeR or DESeq2 and the final study design/covariates.

Project Structure

See docs/PROJECT_STRUCTURE.md for the file map and module dependencies.

Relevant Dropbox Files

The broad lab Dropbox is located at:

/Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox

Most of that Dropbox is unrelated lab, admin, protocol, manuscript, or older project material. The files below are the ones identified as relevant to this current HLHS Parse/TCR Mega single-cell project.

Most Relevant Dropbox Files

• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Parse TCR Mega_Metadata.xlsx Canonical metadata workbook. Exact same SHA-256 as the active data copy in Data/Garcia Lab Data/. Columns match the code contract: ID, Age (Years), Study Group, Surgical Palliation Stage, Thymectomy, Sex, Race, Ethnicity.

• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/scRNASeq_demographics_info_DL_10162025_final.xlsx Broader demographics workbook with scRNAseq_demographics, Parse Metadata, study-group stats, and reference sheets. Relevant, but contains identifiable clinical fields, so handle as sensitive/PHI-adjacent.

• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Trailmaker downloads/422f32d6-4b22-46cd-97d7-430c19f9ed87_unfiltered_matrices.zip Upstream WT expression matrices. Contains per-sample count_matrix.mtx.gz, all_genes.csv.gz, cell_metadata.csv.gz, including output_combined/all-sample/DGE_unfiltered/....

• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Trailmaker downloads/422f32d6-4b22-46cd-97d7-430c19f9ed87_filtered_immune.zip Upstream filtered TCR outputs: per-sample tcr_annotation_airr.tsv, barcode_report.tsv, clonotype_frequency.tsv, tcr_contigs.fa.

• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Trailmaker downloads/422f32d6-4b22-46cd-97d7-430c19f9ed87_unfiltered_immune.zip Upstream unfiltered TCR outputs, same structure as filtered immune archive.

• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Trailmaker downloads/422f32d6-4b22-46cd-97d7-430c19f9ed87_all_summaries.zip Trailmaker analysis summary HTML/CSV/log files for the same sample set.

• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Trailmaker downloads/abe70a7d_settings.txt Relevant Trailmaker settings/provenance, but not identical to the active data_processing_settings.txt; thresholds differ, so treat it as candidate upstream provenance rather than the current canonical settings file.

Also Relevant Supporting Files

These are useful for provenance, sample loading, and library preparation, but are not directly consumed by the repo:

• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Parse TCR Mega 2025_V3.xlsx
• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Garcia_Parse_WT and TCR Sub Libraries (16).xlsx
• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/sublib1_mega_from_html_TB_01072026_V2.xlsx
• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/20260128_LH00407_0221_B23LHNCLT4_L8_Garcia_demux.csv
• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Data Files/20251105_LH00407_0193_A23CFGWLT3_L78_Garcia_summary.csv
• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Data Files/20251110_LH00407_0194_A23CFFCLT3_L2_Garcia_demux.csv
• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/TCR Mega Protocol Notes.docx
• /Users/admin/Library/CloudStorage/GoogleDrive-2arnavmana@gmail.com/My Drive/Garcia-Lab-Dropbox/TCR Mega/Evercode TCR Mega User Manual v1.3.pdf