Bioinformatics Initial Data Analysis

Arguments:

• input_path: Path to data file (.h5ad, .csv, .h5) or directory of CSV files
• --data-type: Data type override (default: auto for auto-detection)
• --subsample: Max cells per group for tractable analysis (default: 500)
• --output-dir: Output directory (default: ./analysis_output)
• --report-style: clinical for plain-language medical summaries, technical for bioinformatics detail (default: clinical)

Output Files:

analysis_output/
├── figures/                    # All generated plots (PNG)
├── processed/
│   └── adata_processed.h5ad   # Processed AnnData object
├── report.html                 # Complete analysis report
└── analysis_summary.json       # Machine-readable summary statistics

Approach 2: Modular Steps

For custom workflows, import individual step modules:

from step1_load_data import load_data
from step2_qc import run_qc
from step3_normalize import normalize_data
from step4_dim_reduction import run_dim_reduction
from step5_clustering import run_clustering
from step6_marker_analysis import run_marker_analysis
from step7_report import generate_report

Each step function accepts an AnnData object and returns the modified AnnData plus a dictionary of results/figures.

Pipeline Steps

Step 1: Data Loading

Load data from various formats into AnnData. For directories of CSVs (e.g., CyTOF per-cell-line files), automatically concatenate with metadata. Apply subsampling if dataset is large.

Step 2: Quality Control

Data-type-aware QC:

• CyTOF: MAD-based outlier detection per marker, signal distributions, batch effects across cell lines
• scRNA-seq: Mitochondrial %, genes per cell, counts per cell, doublet detection
• Universal: Missing value assessment, distribution violin plots, outlier flagging

Step 3: Normalization

• CyTOF: Data is typically pre-transformed (arcsinh). Verify transformation, apply z-score for dim. reduction.
• scRNA-seq: Library size normalization (CPM) -> log1p -> HVG selection -> z-score scaling
• Store raw values in adata.raw for downstream differential analysis.

Step 4: Dimensionality Reduction

PCA with scree plot and loadings analysis, followed by UMAP visualization colored by all available metadata and key markers.

Step 5: Clustering

Leiden graph-based clustering at multiple resolutions. Evaluate with ARI, NMI, Silhouette scores if reference labels exist. Visualize cluster composition across metadata categories.

Step 6: Marker Analysis

Wilcoxon rank-sum differential expression per cluster. Marker correlation heatmap. If treatment/condition metadata exists: treatment response analysis with boxplots and effect heatmaps. If time metadata exists: time-course dynamics.

Step 7: Report Generation

Generate HTML report with embedded figures and interpretations. Two styles:

• Clinical: Written for medical doctors and non-bioinformaticians. Each plot includes "What this shows", "Key findings", and "Clinical relevance" sections.
• Technical: Standard bioinformatics report with methods, parameters, and statistical details.

Reference Files

For detailed guidance, consult:

• references/plot_interpretation_guide.md - How to explain each plot type to non-experts
• references/cytof_specifics.md - CyTOF-specific QC, normalization, and markers
• references/scrnaseq_specifics.md - scRNA-seq-specific processing details
• references/statistical_methods.md - Plain-language glossary of statistical methods

Important Notes

• CyTOF data is often pre-transformed: Check value ranges before applying arcsinh. Values in range [-1, 15] indicate arcsinh-transformed data.
• Large datasets: Always subsample for initial exploration. Use 500-2000 cells per group.
• NaN handling: Always run nan_to_num after z-score scaling — constant-value features produce NaN.
• Leiden timeout: For >50K cells, Leiden clustering may take >10 minutes. Reduce subsample size.
• Report audience: Default to clinical style unless user requests technical detail.