Epigenomics troubleshooting

This page helps you diagnose the common failure modes in epigenomics analysis — peak calling that returns nothing, low FRiP and other signal-quality problems, differential analysis with too few or too many significant regions, sparse methylation calls and missing DMRs, and BAM upload or timeout errors.

Epigenomics troubleshooting

No peaks called from ATAC-seq data

Symptom: Peak calling returns zero or very few peaks.

Fixes:

• Check your BAM file quality. Low read counts (<10 million unique reads) may not provide sufficient signal for peak calling
• Verify the BAM file is sorted and indexed. Unsorted BAMs will produce incorrect results
• Ensure duplicates are marked. PCR duplicates inflate signal at random loci and reduce effective coverage
• Try a different peak_caller (macs2, hmmratac, or genrich) — sensitivity varies by algorithm
• Check that the correct genome assembly is specified. A mismatch between BAM alignment reference and the genome parameter (hg38 or mm10) causes failures
• If FRiP is below 0.05, the experiment likely has insufficient Tn5 insertion signal

Very low FRiP score

Symptom: FRiP is below 0.1 for ATAC-seq or below 0.05 for ChIP-seq.

Fixes:

• Low FRiP indicates high background relative to signal. This is typically an experimental rather than computational issue
• For ATAC-seq: check cell count (50,000-100,000 recommended), Tn5 concentration, and lysis conditions
• For ChIP-seq: check antibody quality, immunoprecipitation efficiency, and input DNA amount
• Mitochondrial reads inflate ATAC-seq background; filter them out of the BAM before upload — the tool does not expose a mitochondrial-filtering parameter
• Verify that duplicate removal was performed. High duplication rates reduce effective library complexity

ChIP-seq peaks look wrong with broad marks

Symptom: H3K27me3 or H3K36me3 peaks are fragmented into many small narrow peaks instead of broad domains.

Fixes:

• Set peak_caller: "sicer2". The default macs3 is tuned for sharp signals and will fragment broad domains
• See the inputs table for recommended peak callers by histone mark

Differential analysis returns no significant regions

Symptom: No regions pass the differential result's FDR threshold (0.05 by default).

Fixes:

• Ensure you have sufficient biological replicates. With only 2 replicates, statistical power is limited and subtle changes will not reach significance
• Verify that the peak files and metadata CSV assign samples to the correct conditions. Swapped labels produce random fold changes
• Check for batch effects. If treatment and control were processed on different days or with different protocols, batch variation may overwhelm biological signal
• Try the other differential method (diffbind vs deseq2) — they use different statistical models
• The absence of significant results may be biologically real -- not all treatments cause epigenomic changes

Differential analysis shows excessive significant regions

Symptom: Thousands of regions are significant, which seems biologically implausible.

Fixes:

• Check for batch effects or sample swap between conditions
• Verify that the peak files for each condition are complete and correctly labeled in the metadata CSV
• Look at the fold change distribution. If most changes are small and in one direction, there may be a global shift rather than region-specific changes

Methylation calling returns very few sites

Symptom: Far fewer CpG sites than expected are reported.

Fixes:

• Check the min_coverage parameter. The default of 5 reads filters out low-coverage sites. For shallow sequencing, reduce to 3 or 1
• Verify that the BAM file is from bisulfite sequencing (not standard WGS). Standard alignment produces zero methylation signal
• Ensure the correct reference genome is specified (hg38 or mm10). Genome mismatches cause alignment artifacts
• For RRBS data, low genome-wide coverage is expected. RRBS enriches CpG islands and will report sites only in CpG-dense regions
• Check bisulfite conversion efficiency. Incomplete conversion (<95%) makes methylation calls unreliable
• Try the other calling method (bismark vs bsmap)

DMR detection finds no DMRs

Symptom: Zero differentially methylated regions detected.

Fixes:

• Try a different DMR method (dmrseq, bsseq, or methylkit) — sensitivity to subtle methylation changes varies by algorithm
• Ensure sufficient replicates (2+ per condition)
• Check that the methylation files have adequate, consistent coverage across the region in all samples
• Verify that the methylation files and metadata CSV assign samples to the correct conditions

BAM file upload fails

Symptom: Error during BAM file upload or processing.

Fixes:

• BAM files must be valid, sorted, and indexed. Run samtools quickcheck your_file.bam locally to verify
• Maximum file size depends on your plan. Very large BAM files (>50 GB) may need to be downsampled
• Ensure the BAI index file accompanies the BAM file. Some upload methods require both files
• Check that the BAM header contains valid sequence dictionary entries matching the selected genome

Analysis times out

Symptom: Peak calling or differential analysis fails with a timeout.

Fixes:

• Very large BAM files (>100 million reads) may exceed processing time limits. Downsample to 50-80 million reads for most analyses
• Reduce the number of conditions or replicates in differential analysis
• For methylation calling on WGBS, process individual chromosomes if whole-genome analysis times out

Getting help

If issues persist:

1. Check the tool error message for specific suggestions
2. Verify your BAM file quality using samtools flagstat and samtools idxstats
3. Try a smaller test BAM file to confirm the tool is working
4. Describe the issue to Ivy

Read next