Note and Acknowledgment

TIPP3 includes and uses:

1. pplacer (v1.1.alpha19).

External requirements

BLAST is a hard requirement to run TIPP3. The software will automatically look for blastn in the $PATH environment variable. If you have not installed BLAST, you can find the latest version from https://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/.

TIPP3 reference package

Install with PyPI (pip)

The easiest way to install TIPP3 is to use the PyPI distribution.

# 1. Install with pip (--user if no root access)
pip install tipp3 [--user]

# 2. Three binary executables will be installed. The first time running
#    any of the binaries will create the TIPP3 config file at
#    ~/.tipp3/main.config
tipp3 [-h]           # (recommended) preset "TIPP3-fast" for abundance profiling
tipp3-accurate [-h]  # preset "TIPP3" for abundance profiling
run_tipp3.py [-h]    # see other options

Install from source files

python>=3.7
configparser>=5.0.0
DendroPy>=4.5.2
setuptools>=60.0.0
treeswift>=1.1.28
witch-msa>=1.0.7
bscampp>=1.0.7

# 1. Install via GitHub repo
git clone https://github.com/c5shen/TIPP3.git

# 2. Install all requirements
pip3 install -r requirements.txt

# 3. Execute run_tipp3.py executable for the first time with "-h" to see
#    allowed commandline parameters and example usages
#    Running TIPP3 for the first time will also create the main config
#    file at "~/.tipp3/main.config", which stores the default behavior
#    for running TIPP3 (including all binary executable paths)
python3 run_tipp3.py [-h]

main.config

main.config file will be created the first time running TIPP3 at the user root directory (~/.tipp3/main.config). This file stores the default behavior for running TIPP3 and the paths to all binary executables that TIPP3 need to use.

User-specified config file

In addition, a user can specify a customized config file with -c or --config-file parameter option when running TIPP3 for abundance profiling (e.g., run_tipp3.py abundance -c user.config). The user.config file will override settings from main.config (if overlaps). Command-line arguments still have the highest priority and will override both config files, if any parameters overlap.

Subcommand abundance

The general command to run TIPP3 for abundance profiling is listed below. By default, preset “TIPP3-fast” is run, which is significantly faster than the more accurate TIPP3 mode. See Examples below for how to customize the TIPP3 pipeline.

# (Optional) change the logging level to DEBUG for more verbose logging
export TIPP_LOGGING_LEVEL=debug

# TIPP3 supports the following formats for "-i [query reads]"
# XXX.fasta[.gz, .gzip]
# XXX.fa[.gz, .gzip]
# XXX.fastq[.gz, .gzip]
# XXX.fq[.gz, .gzip]

python3 run_tipp3.py abundance -r [reference package path] -i [query reads] -d [output directory]

Subcommand detection (TIPP-SD)

TIPP3 can also perform taxon detection at different taxonomic levels (currently only support at the species level). This uses the same set of parameters as the abundance subcommand, with an optional parameter -B to set a custom threshold for reporting detected species. By default, there will be two output files with two different thresholds (convervative for better precision and sensitive for better recall).

# taxon detection (currently only species level)
python3 run_tipp3.py detection -B [detection threshold] ...

Subcommand download_refpkg

Users can also directly download the latest version of the TIPP3 reference package using the subcommand run_tipp3.py download_refpkg.

# download tipp3 refpkg to current directory and decompress
python3 run_tipp3.py download_refpkg -o ./ --decompress

Examples

Some examples of TIPP3 usage can be found at the bottom of the help text running:

python3 run_tipp3.py -h

All of the following examples can be found in the examples/run.sh bash script, with example data stored under examples/data. The default example data used is a small set of Illumina short reads denoted as illumina.small.queries.fasta.

python3 run_tipp3.py abundance -i examples/illumina.small.queries.fasta \
   --reference-package [reference package dir] --outdir tipp3_scenario1 \
   --alignment-method blast --placement-method bscampp \
   -t 16

python3 run_tipp3.py abundance -i examples/illumina.small.queries.fasta \
   --reference-package [reference package dir] --outdir tipp3_scenario2 \
   --alignment-method blast --placement-method pplacer-taxtastic \
   -t 16

python3 run_tipp3.py abundance -i examples/illumina.small.queries.fasta \
   --reference-package [reference package dir] --outdir tipp3_scenario3 \
   --alignment-method witch --placement-method pplacer-taxtastic \
   -t 16 --keeptemp

python3 run_tipp3.py detection -i examples/illumina.small.queries.fasta \
   --reference-package [reference package dir] --outdir tipp3_scenario4 \
   -t 16 -B 0.3