5.9 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.9.1 Pileup fields

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

5.9.2 Histogram fields

Field Description
depth Sequencing depth
qualities Base qualities
contexts Sequencing depth
allelicDepth Allelic depth

5.9.3 Parameters

5.9.3.1 Input

--bam Input_bam_file.bam Input BAM file

5.9.3.2 Specific

Parameter Description Default
--fields field1,field2,field3 Set which pileup fields will be printed (see Pileup fields), all uses all fields refBase, depth, bases, qualities, alleles
--histograms hist1,hist2,hist3 Set which histograms to create (see Histogram fields), all creates all histograms no histrograms
--printAll Print all sites that pass filters, including those without data
--onlyHistograms Only write histogram files, not pileup file

5.9.4 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.

5.9.5 Usage Example

# Simulate a BAM File
atlas simulate

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