Bio Atac Seq Deep Learning Atac

Version Compatibility

Reference examples tested with: chrombpnet 0.1.7+, bpnet-lite 0.6+ (github.com/jmschrei/bpnet-lite), scBasset 0.1.0+ (basenji2 fork), tangermeme 0.1+, tfmodisco-lite 2.2+, DeepLIFT 0.6+, captum 0.7+, tensorflow 2.13+, pytorch 2.1+, kipoi 0.8+.

Verify before use:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version then <tool> --help to confirm flags

If code throws unexpected errors, introspect the installed package and adapt rather than retrying. Deep-learning tooling evolves rapidly; method papers post 2023 may have superseded reference implementations.

Sequence-Based Deep Learning for ATAC-seq

"Score the effect of a GWAS SNP on chromatin accessibility" -> Train (or use pre-trained) sequence-to-accessibility CNNs that take 1-5 kb DNA windows and predict per-base Tn5 cleavage profiles. Outputs include: bias-corrected accessibility, single-base mutation effect predictions, and DeepLIFT contribution scores convertible to motifs via TF-MoDISco.

• CLI: chrombpnet pipeline --bigwig signal.bw --bigwig-bias bias.bw ...
• Python: bpnet-lite for custom architectures; tangermeme for fast scoring
• Python (single-cell): scBasset for per-cell sequence-based predictions
• Python (long-context): Enformer pre-trained models via Kipoi

Sequence models are NOT a replacement for MACS+TOBIAS at every step. They excel at three specific tasks where classical pipelines struggle: (1) Tn5 bias correction in low-complexity sequence contexts, (2) variant effect prediction in non-genic regions, (3) cell-type-specific motif discovery beyond what JASPAR provides.

Algorithmic Taxonomy

Methodology evolves; verify against current Kundaje lab pipelines (chrombpnet GitHub), Greenleaf lab (scBasset), and Avsec / Linder publications before locking pipelines.

When Deep Learning Helps vs When Classical Pipelines Suffice

For most standard ATAC analysis, classical pipelines remain primary. Deep learning enters when (a) variant interpretation is the goal, (b) cell-type prediction is needed beyond observed data, or (c) bias correction quality is paramount (low-input, FFPE, transcription factors with weak motifs).

Per-Tool Failure Modes

chromBPNet -- Bias model mismatch

Trigger: Training the bias model on a dataset different from the accessibility dataset (e.g. K562 bias model used on primary T cells).

Mechanism: chromBPNet's bias model captures sequence-specific Tn5 preference, which is mostly cell-type-invariant BUT contributions of chromatin context at cuts can vary. Cross-celltype bias models work but with degraded performance.

Symptom: Predicted footprints look correct at known TFs (CTCF) but fail on cell-type-specific regulators.

Fix: Train a per-cell-type bias model from naked-DNA control if available, OR use the chromBPNet authors' pre-trained k562 / GM12878 / HepG2 bias as a fallback (acknowledged degradation).

chromBPNet -- Insufficient training data

Trigger: Training on < 50M deduplicated nuclear reads, or < 30k peaks.

Mechanism: CNN training needs enough peaks for stable gradient updates and enough background regions for the dual-task loss.

Fix: Pool replicates before training; reduce model capacity (--num-filters); use pre-trained model on closest cell type and skip retraining.

BPNet / chromBPNet -- DeepLIFT vs Integrated Gradients confusion

Trigger: Computing per-base contributions for motif discovery.

Mechanism: DeepLIFT (RevealCancel rule) and Integrated Gradients (50 baseline samples) give different attribution patterns. DeepLIFT preserves additivity; IG is stochastic.

Fix: Use DeepLIFT rescale-rule (chromBPNet default) for TF-MoDISco. IG only when DeepLIFT fails on saturating activations. Document the choice.

scBasset -- Cell projection layer instability

Trigger: Few cells per cluster; sparse training data.

Mechanism: scBasset learns a per-cell projection vector; with < 100 cells per cluster the projection is noisy.

Fix: Aggregate cells to clusters before training, OR use chromBPNet trained on pseudobulks per cluster instead.

Enformer -- Pre-trained models lack target cell type

Trigger: Using Enformer for variant effects in a cell type not in its training set (e.g. GTEx tissues are covered; novel primary cell types are not).

Mechanism: Enformer's outputs are per-track predictions; if the target cell type wasn't trained, the agent can use a similar track as proxy but accuracy degrades.

Fix: Use a similar tissue track as proxy (HepG2 for liver biology; GM12878 for B-cell-like) OR fine-tune Enformer on custom data (expensive). Document the proxy.

tangermeme -- Marginal vs in silico mutagenesis confusion

Trigger: Asking for a "variant effect score" without specifying the formula.

Mechanism: Marginal effects = ref vs alt at the SNP only. ISM = saturation across all positions in the window (every base mutated). Different magnitudes; different questions.

Fix: Define which calculation. For GWAS variant prediction, use marginal at the SNP (matches phenotype-genotype coupling). For motif discovery, use ISM.

Decision Tree by Goal

chromBPNet Standard Pipeline

Goal: Train a bias-corrected CNN that predicts per-base accessibility from sequence, then score variants with it.

Approach: Generate train/valid/test chromosome splits, train the Tn5 bias model on background regions, train the accessibility model with bias correction, then run the standalone variant-scorer repo to predict ref-vs-alt effects at SNPs.

# 1. Generate train / valid / test chromosome splits (output is a JSON file with chrom assignments)
chrombpnet prep splits \
    -c hg38.chrom.sizes \
    -tcr chr1 chr3 chr6 \
    -vcr chr8 chr20 \
    -op splits/fold_0
# Train chromosomes are auto-inferred (whatever is not in -tcr/-vcr). The `-tecr` flag does NOT exist.

# 2. Train bias model from background regions
chrombpnet bias pipeline \
    -ibam atac.bam \
    -d ATAC \
    -g hg38.fa \
    -c hg38.chrom.sizes \
    -p peaks.narrowPeak \
    -n nonpeaks.bed \
    -fl splits/fold_0.json \
    -b 0.5 \
    -o bias_model/

# 3. Train accessibility model with bias correction
chrombpnet pipeline \
    -ibam atac.bam \
    -d ATAC \
    -g hg38.fa \
    -c hg38.chrom.sizes \
    -p peaks.narrowPeak \
    -n nonpeaks.bed \
    -fl splits/fold_0.json \
    -b bias_model/models/bias.h5 \
    -o output/

# 4. Variant effect prediction at GWAS SNPs uses the SEPARATE kundajelab/variant-scorer repo
# (the `chrombpnet snp_score` subcommand is commented out in current chrombpnet/parsers.py)
git clone https://github.com/kundajelab/variant-scorer
python variant-scorer/src/variant_scoring.py \
    --model output/models/chrombpnet_nobias.h5 \
    --list variants.tsv \
    --genome hg38.fa \
    --chrom_sizes hg38.chrom.sizes \
    --out_prefix variants_predicted
# Output: variants_predicted.variant_scores.tsv with per-SNP log2FC magnitudes

-b 0.5 is the bias threshold factor (--bias-threshold-factor); chromBPNet docs recommend a start value of 0.5 for ATAC (0.8 for DNase). For variant scoring, use the standalone kundajelab/variant-scorer companion repo, NOT a chrombpnet subcommand. Verify exact flag names with python variant_scoring.py --help because the API evolves.