5.8 pileup

Printing pileup from BAM file

pileup processes the BAM file and, for each genomic position, reports the bases observed in the reads that map there. It also computes genotype likelihoods (GTL) and applies all standard input filters while doing so. Additional per‑site information can be included as needed. If a post-mortem damage pattern or a base quality score recalibration table is provided, these will be taken into account in the estimated genotype likelihoods. See estimateErrors for more information on how to produce a post-mortem damage pattern and base quality score recalibration.

5.8.1 Input

Required inputs :

--bam Input_bam_file.bam

Input BAM file

Optional inputs :

--recal recal.txt or --RGInfo rginfo.json	Quality score recalibration file (see estimateErrors for further information).
--pmd Input_PMD.txt or --RGInfo rginfo.json	Post-mortem damage parameters (see estimateErrors for further information).

Specific Parameters :

--fields field1,field2,field3	Set which pileup fields will be printed. By default, the fields depth, bases, qualities and alleles are included. Additional fields that can be enabled are: refBase, context1, context2, readGroups, sampleBases, mates, strands, likelihoods, and hml. See the pileup fields table for additional information on all available fields.
--printAll	Print all sites that pass filters, including those without data. By default, only sites with data will be printed.
--histograms histogram_to_print	Print the counts for following histogram parameters: Sequencing depth depth, Base qualities qualities), Base contextscontexts, Allelic depthallelicDepth| |–onlyHistograms`

5.8.2 Output

*_pileup.txt.gz	Text file containing, for each genomic position, the pileup fields selected via --fields (or the default set). This typically includes sequencing depth, observed bases, and genotype likelihoods, and may include any additional enabled fields. All reported values reflect any applied PMD or recalibration filters.
*_depthPerChromosome.txt.gz	Text file containing the mean sequencing depth of each chromosome.
*_depthPerWindow.txt.gz	Text file containing the mean sequencing depth of each window.
*_allelicDepth.txt.gz (optional)	Text file summarizing how often each distinct pattern of base counts occurs across all processed sites. For each count pattern, the file lists the corresponding depth, major and minor alleles (with their depths), and the number of sites matching that pattern. This file is only produced when the --histograms argument is used.
*_contextInformation.txt.gz (optional)	Text file summarizing, for each base‑quality value, how often each two‑base context (e.g., AA, AC, AG, …, NT) occurs across all processed sites. Each row corresponds to a specific base quality, and each column gives the count of sites where a read with that quality shows the corresponding dinucleotide context. This file is only produced when the --histograms argument is used.
*_depthPerSiteHistogram.txt.gz (optional)	Text file containing a histogram of per‑site sequencing depth. Each row lists a depth value and the number of genomic positions observed with that depth. This file is only produced when the --histograms argument is used.
*_qualHistogram.txt.gz (optional)	Text file containing a histogram of base‑quality values. The file first lists the aggregated counts across all read groups, followed by separate histograms for each individual read group. Each row reports a read group, a base‑quality score, and the number of bases observed with that quality. This file is only produced when the --histograms argument is used.
*_filterSummary.txt	Text file summarizing how many reads were excluded by each filtering category. The first row (allReadGroups) gives totals across all read groups, followed by one row per individual read group.

5.8.3 Usage Example

#! /bin/bash

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

# Simulate a BAM File
$atlas simulate

# Create pileup file
$atlas pileup --bam ATLAS_simulations.bam

5.8.4 Pileup fields

Field	Description
depth	Total number of reads covering the position. Included by default.
bases	Observed bases at the position. Included by default.
qualities	Base‑quality characters corresponding to bases. Included by default.
alleles	Counts of A, C, G, T and the number of distinct alleles. Included by default.
refBase	Reference base at the position. Optional.
context1	One‑base upstream context (previous base). Optional.
context2	Two‑base upstream context (previous two bases). Optional.
readGroups	Read group IDs contributing bases at this position. Optional.
sampleBases	Sampled bases per BAM file (one for each). Optional.
mates	Mate information for bases at this position (e.g., mate orientation and counts of first and second mates). Optional.
strands	Strand orientation of bases at the position, as well as counts of forward and reverse strand reads. Optional.
likelihoods	Genotype likelihoods. Optional.
hml	Boolean indicating whether the heterozygous genotype is the most likely one. Optional.