---
title: Epigenomics troubleshooting
description: >-
  Resolve peak calling failures, low signal quality, differential analysis
  issues, and methylation calling errors.
tags:
  - epigenomics
  - troubleshooting
---

This page helps you diagnose the common failure modes in [epigenomics](/docs/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](/docs/epigenomics/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