5.10 pileupToBed

Create bed file from pileup file

pileupToBed converts per‑site depth information from pileup files into BED intervals. It has three options:

  1. Learn Negative binomial distribution
    The default option. pileupToBed automatically learns an appropriate range by building a depth histogram from the input pileup files and fitting a negative binomial distribution around the mode of the depth distribution. The learned range is then used to create a BED file. This procedure is particularly useful when pileup has been run over multiple BAM files.

  2. Learn Heterogametic binomial distribution
    Learns binomial distribution of heterogamete samples (--hetero) vs all samples. Creates a BED file where all outlies of this distribution are masked.

  3. User depth range
    Creates a BED file containing only positions whose depth falls within the provided depth (--depth)

5.10.1 Parameters

5.10.1.1 Input

--pileup pileup.txt.gz Pileup file containing all samples.
--hetero heterogametes.txt.gz Optional pileup file, containing only heterogamete samples.
--fasta Input.fasta Reference genome
--fai Input.fai index file of reference genome
--histogram hist.txt One or more histogram files containing depth‑frequency information. These are used only when no explicit depth range is provided, allowing pileupToBed to learn the depth range without traversing pileup files.
  • When creating a BED-file --pileup and either --fasta or --fai are required
  • If --hetero is given, a heterogametic binomial distribution will be learned instead of a negative binomial distribution
  • --histogram will only learn negative binomial distribution and output range, no BED file will be created

5.10.1.2 Specific

--depth integer_value1,integer_value2 User‑defined depth range used to select positions from the pileup file (e.g., [7,30)). Only positions whose depth falls inside this interval are merged into BED intervals. If omitted, pileupToBed automatically learns an appropriate depth range from the input pileup files and outputs a depth histogram.
--fitSection float_value Defines the window around the depth distribution’s mode used when fitting the negative binomial model in automatic depth‑learning mode. The default is mode ± 0.2 * mode, and only depths within this section are used for parameter estimation.
--quantile float_value Controls how much of the fitted negative binomial distribution is retained. The specified quantile (by default 0.95) is used to keep the middle quantile fraction of the distribution. The resulting interval [rangeMin, rangeMax] is then used as the learned depth range.
--writeMask Invert the depth filter when producing BED output. Instead of writing regions where the depth satisfies the specified range, pileupToBed writes regions where the depth does not fall within that range.

5.10.1.3 Engine

5.10.2 Output

*_regions.bed 0-based BED-file with regions to use. Only produced when --writeMask is not set.
*_mask.bed 0-based BED-file with regions to mask. Only produced when --writeMask is set.
*_hist.txt Histogram listing the counts for each depth value. Only produced when --depth is not set.

5.10.3 Usage Example

# Simulate 5 BAM Files in Hardy–Weinberg Equilibrium
atlas simulate --type HW --sampleSize 5

# Create pileup file of all bam files and name it multiBam
atlas pileup --bam "$(ls *.bam | tr '\n' ',')" --out multiBam

# Create bed file from pileup output with 5 <= depth < 30
atlas pileupToBed --pileup multiBam_pileup.txt.gz --fai ATLAS_simulations.fasta.fai --depth "[10,30)"