Phanta

Rapidly quantify taxa from all domains of life, directly from short-read human gut metagenomes

The foundation of this workflow is a comprehensive, virus-inclusive database of genomes with integrated taxonomic information

Workflow figure created on BioRender.com.

Citation

Pinto, Y., Chakraborty, M., Jain, N. et al. Phage-inclusive profiling of human gut microbiomes with Phanta. Nature Biotechnology (2023). https://doi.org/10.1038/s41587-023-01799-4

Updates

• 08 Jul 2025 - Update to Phanta env, based on recommendations from users.
• 28 May 2024 - New tutorial for making custom Phanta DBs!
• 28 Sep 2023 - New Phanta Databases! 1) Utilizing the Unified Human Gut Virome Catalog (UHGV) for the viral portion of Phanta database instead of MGV+Refseq Viral. 2) The default Phanta database used HumGut for its prokaryotic portion. As HumGut filtered out lowly prevalent bacteria (like Salmonella enterica) we have compiled an additional database with UHGG2.0 as the source for the prokaryotic portion.
• 18 Aug 2023 - Thanks to Phanta user @telatin, we now have added a runner script (called run_phanta.py) to the root of this repository. This runner script may simplify Phanta execution, especially if you use Phanta regularly. For usage instructions, please see RUNNER.md. Please note that we have not tested this extensively and we recommend reading through the below information before trying to execute Phanta with the runner script.

Table of contents

1. Quick Start
   • Installation
   • Test Your Installation
   • Basic Usage
   • Main Outputs
2. Advanced
   • Advanced Usage
   • Additional Outputs
   • Provided Postprocessing Scripts
     • Filtering Merged Tables to a Specific Taxonomic Level
     • Filtering Merged Tables by Prevalence of Taxa
     • Modifying Merged Tables to OTU Format
     • Collapse Viral Abundances by Predicted Host
     • Calculate Viral Lifestyle Statistics
     • Calculation of Cross-Domain Correlations
     • Determine Which Detected Viruses are Likely Integrated Prophages
3. Troubleshooting
   • Environment Creation
   • Stalled Snakemake Pipeline

Quick Start

Installation

Step One - Clone the repository

Clone the repository to the desired location on your system using the following command:

git clone https://github.com/bhattlab/phanta.git

Step Two - Install conda, if not already installed

If you do not already have conda installed, please install using the instructions provided here.

Step Three - Create and activate a new conda environment

Create a new conda environment via the following command, replacing /full/path/to/cloned/repo with the appropriate path to your cloned repository:

    # If you use strict or flexible channel priority, first remove the setting
conda config --set channel_priority false
conda env create -n phanta_env --file /full/path/to/cloned/repo/phanta_env.yaml

Activate the environment by executing:

conda activate phanta_env

If you have trouble creating the environment using the above commands, you can alternatively follow the instructions here.

Step Four - Download Phanta's default database

Create a directory to store Phanta's default database of genomes. For example:

mkdir phanta_dbs
cd phanta_dbs

Then execute the following commands:

wget http://ab_phanta.os.scg.stanford.edu/Phanta_DBs/database_V1.tar.gz
tar xvzf database_V1.tar.gz

The list of files that should be extracted is detailed here. Note alternative databases are also available, please see our databases list. As described on that page, you can also make a custom Phanta DB.

Test Your Installation

To test that you are ready to run Phanta on your data, navigate to your cloned repository using cd and download the four .fq.gz files required for testing via the following command:

wget http://ab_phanta.os.scg.stanford.edu/Phanta_DBs/test_dataset.tar.gz

tar xvzf test_dataset.tar.gz

Then edit two files contained in the testing subdirectory of your cloned repository. 1. Edit samp_file.txt by replacing /full/path/to/cloned/repo in the four locations indicated with the full path to your cloned repository. 2. Edit config_test.yaml by replacing: * /full/path/to/cloned/repo in the three locations indicated with the full path to your cloned repository. * /full/path/to/downloaded/database in the one location indicated with the full path to the database you downloaded during the install.

Finally, execute the Snakemake command below, after replacing: 1. /full/path/to/cloned/repo with the path to your cloned repository 2. The number provided to max-threads with the maximum number of threads you have available. Note that if this number is greater than 16, you can (but don't need to) also increase the argument to class_threads in config_test.yaml.

Note At least 32GB memory is required. Also, you may have to replace the --cores and max-threads arguments with a profile for Snakemake execution depending on your setup (e.g., replace with --profile slurm).

snakemake -s /full/path/to/cloned/repo/Snakefile \
--configfile /full/path/to/cloned/repo/testing/config_test.yaml \
--jobs 99 --cores 1 --max-threads 16

When execution has completed, please check that your test_dataset directory has an empty file called pipeline_completed.txt. You should also have two new subdirectories in test_dataset - classification and final_merged_outputs - which should have identical contents to the corresponding subdirectories in the testing subdirectory of your cloned repository. You will also have two additional files ending in *krak within test_dataset/classification/intermediate.

Basic Usage

For basic usage, replace the four paths at the top of the provided config.yaml file as appropriate.

You do not need to make any additional changes except if: 1) you did not conduct 150bp sequencing, or 2) if your read files are not gzipped. In those cases, you may also need to change the read_length or gzipped parameters, which are described under Advanced Usage.

After you have finished editing your config file, execute a similar Snakemake command to the one you used to Test Your Installation, example below:

snakemake -s /full/path/to/cloned/repo/Snakefile \
--configfile /full/path/to/cloned/repo/config.yaml \
--jobs 99 --cores 1 --max-threads 16

When the pipeline is done, you will have an empty file in your designated output directory called pipeline_completed.txt.

Main Outputs

The main outputs are merged tables that list the abundance of each taxon, in each sample. Rows are taxa and columns are samples.

• final_merged_outputs/counts.txt: provides the number of read (pairs) assigned to each taxon

• final_merged_outputs/relative_read_abundance.txt: same as counts.txt but normalized out of the total number of reads in each sample that were ultimately assigned to any taxon during abundance estimation.

• final_merged_outputs/relative_taxonomic_abundance.txt: similar to relative_read_abundance.txt but abundances are corrected for genome length. In addition, only species (and not higher taxonomic levels) are included in this report.

For examples of the above outputs, please see the testing/final_merged_outputs subdirectory.

Note: To filter counts.txt or relative_read_abundance.txt to a specific taxonomic level (e.g., species, genus), or to change relative_taxonomic_abundance.txt to a higher taxonomic level than species, please refer to Filtering Merged Tables to a Specific Taxonomic Level under Provided Postprocessing Scripts.

Advanced

Advanced Usage

This section contains a description of the additional parameters in the config file that were not mentioned under Basic Usage but can be altered if desired.

Parameters under Specifications for step one - classification of metagenomic reads

• confidence_threshold (default 0.1). This parameter can range from 0 to 1. Higher values yield more confident classifications but reduce sensitivity. Please see this link from the Kraken2 documentation for more details.
• gzipped (default True). This parameter should be True if your read files are gzipped, otherwise False.
• class_mem_mb (default 32768). This parameter specifies the memory in megabytes used for the classification step.
• class_threads (default 16). This parameter specifies the number of threads used for the classification step.

Parameters under Specifications for step two - filtering false positive species

• cov_thresh_viral (default 0.1). This parameter can range from 0 to 1 and specifies a genome coverage requirement for a viral species to be considered a "true positive" in a sample. For example, if this parameter is 0.1, that means that for a viral species to be considered a true positive in a sample, at least one genome of the species must be at least 10% covered by sample reads.
  • Each genome's coverage is estimated by dividing:
    • The number of unique minimizers in the genome that are covered by sample reads, by
    • The total number of unique minimizers in the genome.
  • Terminology note - minimizers are very similar to kmers; for a more detailed description of what they are, please see the Kraken2 paper.
• minimizer_thresh_viral (default 0). This parameter can take any value >= 0 and specifies an additional requirement for a viral species to be considered true positive in a sample. E.g., if this parameter is 10, that means at least one genome of the species must have 10+ of its unique minimizers covered by sample reads.
• cov_thresh_bacterial and minimizer_thresh_bacterial are the analogous parameters for filtering bacterial species.
• Sample sequencing depth may affect the choice of bacterial/viral coverage thresholds - please see our suggested coverage thresholds by sequencing depth, below. These suggestions were based on evaluating the sensitivity/specificity (TPR/FDR) tradeoff at various coverage thresholds and sequencing depths, as described in our manuscript in greater detail.
• As of release 1.1, upon user request we have also added coverage and minimizer parameters for archaeal and eukaryotic species (cov_thresh_arc, cov_thresh_euk, minimizer_thresh_arc, minimizer_thresh_euk).

Parameters under Specifications for step three - per-species abundance estimation

• read_length (default 150). This parameter specifies the read length. Currently the default database is compatible with 75, 100, 120, or 150, and the alternative databases are compatible with 100 or 150. Additional read lengths can be requested here.

• filter_thresh (default 10). This parameter specifies one last false positive species filter - how many sample reads must have been classified to species X (in step one) for it to be considered truly present in the sample? This parameter is specific to the Bracken tool used for abundance estimation and is equivalent to the threshold parameter described in the original Bracken documentation. Note that this filter is uniform across all types of species (e.g., viral, bacterial).

Additional parameters

• database. Phanta is typically run with the default database linked above under Step Four of Installation. However, as described in our manuscript, an alternative version of Phanta's default database was also created, in which prophage sequences have been "masked" in prokaryotic genomes. The download link for this database is: http://ab_phanta.os.scg.stanford.edu/Phanta_DBs/masked_db_v1.tar.gz . All available databases are described here.

• delete_intermediate (default True). Specify True if you would like intermediate outputs to be deleted, otherwise False. Intermediate outputs are per-sample outputs generated during the execution of Steps 1 and 2. Examples of these intermediate files can be found within the testing/classification/intermediate subdirectory of the cloned repository.

Additional Outputs

In addition to the merged tables provided in the final_merged_outputs subdirectory (see Main Outputs), the pipeline provides per-sampl