5.9 pileupToBed

Create bed file from pileup file

pileupToBed converts per‑site depth information from pileup files into BED intervals. If a depth range is provided via --depth, only positions whose depth falls within that range are merged into BED regions. If no depth range is specified, 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 define the BED intervals. This procedure is particularly useful when pileup has been run over multiple BAM files.

5.9.1 Input

Required inputs :

--pileup pileup.txt.gz

Pileup output file

Optional inputs :

--fasta Input.fasta	FASTA file to specify chromosome order.
--fai Input.fai	fai file to specify chromosome order.
--histogram	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.

Specific Parameters :

--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.9.2 Output

*_regions.bed	0-based BED-file with regions within the depth-mask. Only produced when --writeMask is not set.
*_mask.bed	0-based BED-file with regions outside the depth-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.9.3 Usage Example

#! /bin/bash

# Set atlas path
atlas=$(dirname "$0")/../build/atlas

# 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)"