Beta tutorial Please report any issues in the comments section.
Overview
PathSeq is a GATK pipeline for detecting microbial organisms in short-read deep sequencing samples taken from a host organism (e.g. human). The diagram below summarizes how it works. In brief, the pipeline performs read quality filtering, subtracts reads derived from the host, aligns the remaining (non-host) reads to a reference of microbe genomes, and generates a table of detected microbial organisms. The results can be used to determine the presence and abundance microbial organisms as well as to discover novel microbial sequences.
![]()
PathSeq pipeline diagram Boxes outlined with dashed lines represent files. The green boxes at the top depict the three phases of the pipeline: read quality filtering / host subtraction, microbe alignment, and taxonomic abundance scoring. The blue boxes show tools used for pre-processing the host and microbe references for use with PathSeq.
Tutorial outline
This tutorial describes:
- How to run the full PathSeq pipeline on a simulated mixture of human and E. coli reads using pre-built small-scale reference files
- How to prepare custom host and microbe reference files for use with PathSeq
A more detailed introduction of the pipeline can be found in the PathSeqPipelineSpark tool documentation. For more information about the other tools, see the Metagenomics section of the GATK documentation.
How to obtain reference files
Host and microbe references must be prepared for PathSeq as described in this tutorial. The tutorial files provided below contain references that are designed specifically for this tutorial and should not be used in practice. Users can download recommended pre-built reference files for use with PathSeq from the GATK Resource Bundle FTP server in /bundle/pathseq/ (see readme file). This tutorial also covers how to build custom host and microbe references.
Tutorial Requirements
The PathSeq tools are bundled with the GATK 4 release. For the most up-to-date GATK installation instructions, please see https://github.com/broadinstitute/gatk. This tutorial assumes you are using a POSIX (e.g. Linux or MacOS) operating system with at least 2Gb of memory.
Obtain tutorial files
Download tutorial_10913.tar.gz from the ftp site. Extract the archive with the command:
> tar xzvf pathseq_tutorial.tar.gz
> cd pathseq_tutorial
You should now have the following files in your current directory:
- test_sample.bam : simulated sample of 3M paired-end 151-bp reads from human and E. coli
- hg19mini.fasta : human reference sequences (indexed)
- e_coli_k12.fasta : E. coli reference sequences (indexed)
- e_coli_k12.fasta.img : PathSeq BWA-MEM index image
- e_coli_k12.db : PathSeq taxonomy file
Run the PathSeq pipeline
The pipeline accepts reads in BAM format (if you have FASTQ files, please see this article on how to convert to BAM). In this example, the pipeline can be run using the following command:
> gatk PathSeqPipelineSpark \
--input test_sample.bam \
--filter-bwa-image hg19mini.fasta.img \
--kmer-file hg19mini.hss \
--min-clipped-read-length 70 \
--microbe-fasta e_coli_k12.fasta \
--microbe-bwa-image e_coli_k12.fasta.img \
--taxonomy-file e_coli_k12.db \
--output output.pathseq.bam \
--scores-output output.pathseq.txt
This ran in 2 minutes on a Macbook Pro with a 2.8GHz Quad-core CPU and 16 GB of RAM. If running on a local workstation, users can monitor the progress of the pipeline through a web browser at http://localhost:4040.
Interpreting the output
The PathSeq output files are:
- output.pathseq.bam : contains all high-quality non-host reads aligned to the microbe reference. The YP read tag lists the NCBI taxonomy IDs of any aligned species meeting the alignment identity criteria (see the --min-score-identity and --identity-margin parameters). This tag is omitted if the read was not successfully mapped, which may indicate the presence of organisms not represented in the microbe database.
- output.pathseq.txt : a tab-delimited table of the input sample’s microbial composition. This can be imported into Excel and organized by selecting Data -> Filter from the menu:
| tax_id |
taxonomy |
type |
name |
kingdom |
score |
score_normalized |
reads |
unambiguous |
reference_length |
| 1 |
root |
root |
root |
root |
189580 |
100 |
189580 |
189580 |
0 |
| 131567 |
root cellular_organisms |
no_rank |
cellular_organisms |
root |
189580 |
100 |
189580 |
189580 |
0 |
| 2 |
... cellular_organisms Bacteria |
superkingdom |
Bacteria |
Bacteria |
189580 |
100 |
189580 |
189580 |
0 |
| 1224 |
... Proteobacteria |
phylum |
Proteobacteria |
Bacteria |
189580 |
100 |
189580 |
189580 |
0 |
| 1236 |
... Proteobacteria Gammaproteobacteria |
class |
Gammaproteobacteria |
Bacteria |
189580 |
100 |
189580 |
189580 |
0 |
| 91347 |
... Gammaproteobacteria Enterobacterales |
order |
Enterobacterales |
Bacteria |
189580 |
100 |
189580 |
189580 |
0 |
| 543 |
... Enterobacterales Enterobacteriaceae |
family |
Enterobacteriaceae |
Bacteria |
189580 |
100 |
189580 |
189580 |
0 |
| 561 |
... Enterobacteriaceae Escherichia |
genus |
Escherichia |
Bacteria |
189580 |
100 |
189580 |
189580 |
0 |
| 562 |
... Escherichia Escherichia_coli |
species |
Escherichia_coli |
Bacteria |
189580 |
100 |
189580 |
189580 |
0 |
| 83333 |
... Escherichia_coli Escherichia_coli_K-12 |
no_rank |
Escherichia_coli_K-12 |
Bacteria |
189580 |
100 |
189580 |
189580 |
0 |
| 511145 |
... Escherichia_coli_str._K-12_substr._MG1655 |
no_rank |
Escherichia_coli_str._K-12_substr._MG1655 |
Bacteria |
189580 |
100 |
189580 |
189580 |
4641652 |
Each line provides information for a single node in the taxonomic tree. A "root" node corresponding to the top of the tree is always listed. Columns to the right of the taxonomic information are:
- score : indicates the amount of evidence that this taxon is present, based on the number of reads that aligned to references in this taxon. This takes into account uncertainty due to ambiguously mapped reads by dividing their weight across each possible hit. It it also normalized by genome length.
- score_normalized : the same as score, but normalized to sum to 100 within each kingdom.
- reads : number of mapped reads (ambiguous or unambiguous)
- unambiguous : number of unambiguously mapped reads
- reference_length : reference length (in bases) if there is a reference assigned to this taxon. Unlike scores, this number is not propagated up the tree, i.e. it is 0 if there is no reference corresponding directly to the taxon. In the above example, the MG1655 strain reference length is only shown in the strain row (4,641,652 bases).
In this example, one can see that PathSeq detected 189,580 reads reads that mapped to the strain reference for E. coli K-12 MG1655. This read count is propogated up the tree (species, genus, family, etc.) to the root node. If other species were present, their read counts would be listed and added to their corresponding ancestral taxonomic classes.
Microbe discovery
PathSeq can also be used to discover novel microorganisms by analyzing the unmapped reads, e.g. using BLAST or de novo assembly. To get the number of non-host (microbe plus unmapped) reads use the samtools view command:
> samtools view –c output.pathseq.bam
189580
Since the reported number of E. coli reads is the same number of reads in the output BAM, there are 0 reads of unknown origin in this sample.
Preparing Custom Reference Files
Custom host and microbe references must both be prepared for use with PathSeq. The references should be supplied as FASTA files with proper indices and sequence dictionaries. The host reference is used to build a BWA-MEM index image and a k-mer file. The microbe reference is used to build another BWA-MEM index image and a taxonomy file. Here we assume you are starting with the FASTA reference files that have been properly indexed:
- host.fasta : your custom host reference sequences
- microbe.fasta : your custom microbe reference sequences
Build the host and microbe BWA index images
The BWA index images must be build using BwaMemIndexImageCreator:
> gatk BwaMemIndexImageCreator -I host.fasta
> gatk BwaMemIndexImageCreator -I microbe.fasta
Generate the host k-mer library file
The PathSeqBuildKmers tool creates a library of k-mers from a host reference FASTA file. Create a hash set of all k-mers in the host reference with following command:
> gatk PathSeqBuildKmers \
--reference host.fasta \
-O host.hss
Build the taxonomy file
Download the latest RefSeq accession catalog RefSeq-releaseXX.catalog.gz, where XX is the latest RefSeq release number, at:
ftp://ftp.ncbi.nlm.nih.gov/refseq/release/release-catalog/
Download NCBI taxonomy data files dump (no need to extract the archive):
ftp://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump.tar.gz
Assuming these files are now in your current working directory, build the taxonomy file using PathSeqBuildReferenceTaxonomy:
> gatk PathSeqBuildReferenceTaxonomy \
-R microbe.fasta \
--refseq-catalog RefSeq-releaseXX.catalog.gz \
--tax-dump taxdump.tar.gz \
-O microbe.db
Example reference build script
The preceding instructions can be conveniently executed with the following bash script:
#!/bin/bash
set -eu
GATK_HOME=/path/to/gatk
REFSEQ_CATALOG=/path/to/RefSeq-releaseXX.catalog.gz
TAXDUMP=/path/to/taxdump.tar.gz
echo "Building pathogen reference..."
$GATK_HOME/gatk BwaMemIndexImageCreator -I microbe.fasta
$GATK_HOME/gatk PathSeqBuildReferenceTaxonomy -R microbe.fasta --refseq-catalog $REFSEQ_CATALOG --tax-dump $TAXDUMP -O microbe.db
echo "Building host reference..."
$GATK_HOME/gatk BwaMemIndexImageCreator -I host.fasta
$GATK_HOME/gatk PathSeqBuildKmers --reference host.fasta -O host.hss
Troubleshooting
Java heap out of memory error
Increase the Java heap limit. For example, to increase the limit to 4GB with the --java-options flag:
> gatk --java-options "-Xmx4G" ...
This should generally be set to a value greater than the sum of all reference files.
The output is empty
The input reads must pass an initial validity filter, WellFormedReadFilter. A common cause of empty output is that the input reads do not pass this filter, often because none of the reads have been assigned to a read group (with an RG tag). For instructions on adding read groups, see this article, but note that PathSeqPipelineSpark and PathSeqFilterSpark do not require the input BAM to be sorted or indexed.
