PGPTracker: A Bioinformatics Pipeline for Functional Prediction and Analysis

PGPTracker is a command-line interface (CLI) tool designed to automate the complete workflow from 16S rRNA sequencing data to in-depth functional and statistical analysis.

It connects Amplicon Sequence Variants (ASVs) to predicted functions (KEGG Orthologs) and maps them to Plant Growth-Promoting Traits (PGPTs).

Core Workflow

The pipeline is split into two main stages and includes a graphical interface for exploration:

• Stage 1 (process): Handles data processing to generate unstratified (Function x Sample) and stratified (Taxon x Function x Sample) abundance tables. Utilizes optimized hybrid batching for memory efficiency.
• Stage 2 (analysis): Takes the tables from Stage 1 and performs normalization (CLR), statistical analysis (Kruskal-Wallis, PERMANOVA), machine learning (Random Forest, Lasso, Boruta), and generates publication-quality visualizations (PCA, Heatmaps, Volcano Plots).
• Data Explorer (gui): A browser-based interactive dashboard to explore results, visualize patterns, and compare groups dynamically.

Installation

PGPTracker is a pip-installable package that requires Conda to manage its bioinformatics dependencies (QIIME 2 and PICRUSt2).

Step 1: Create and Activate Base Environment

Create and activate a clean Conda environment (Python 3.10+ recommended).

conda create -n pgptracker python=3.13
conda activate pgptracker

Step 2: Install PGPTracker

Install the package and its core dependencies from PyPI (or local source).

pip install pgptracker

Step 3: Run Internal Setup (Mandatory)

This command is mandatory. It automatically creates and configures the separate qiime2 and PICRUSt2 Conda environment that PGPTracker needs to run external tools.

pgptracker setup

Quick Start

1. Interactive Mode (Recommended for Beginners)

The easiest way to run PGPTracker is via the interactive menu, which prompts for all necessary inputs.

pgptracker -i

2. Command Line Mode (For Scripts/Advanced Users)

Stage 1: Process Raw Data

Process your raw sequence data (.qza, .fna, or .biom) into PGPT abundance tables.

Note: The default classifier is greengenes.2024.09 for v4 16S, you can add a custom one if you want or need

pgptracker process \
    --rep-seqs path/to/dna-sequences.fasta \
    --feature-table path/to/feature-table.biom \
    -o my_project_output \
    --classifier-qza /path/to/custom_classifier.qza \
    --stratified \
    --tax-level Genus \
    --max-nsti 1.7 \
    --pgpt-level Lv3 

Note: You can also run each step of the stage 1 separately, try pgptracker -h for more information.

Stage 2: Statistical Analysis & ML

Analyze the output against your metadata to find significant differences and predictive features.

pgptracker analysis \
    -i my_project_output/genus_stratified_pgpt.tsv \
    -m path/to/metadata.tsv \
    -o my_project_output/analysis_results \
    --group-col Treatment \
    --target-col pH \
    --ml-type regression

GUI: Interactive Exploration

Launch the web dashboard to explore your results visually.

pgptracker gui

Command Reference

Main Commands

pgptracker process (Stage 1) Arguments

pgptracker analysis (Stage 2) Arguments

pgptracker clr Arguments

Outputs Structure

PGPTracker generates a structured results folder:

Performance Tuning

PGPTracker includes a custom Memory Profiler to help manage resources on large datasets.

You can enable profiling on any command by adding the --profile flag:

# Profiles using the 'production' preset (warns if >5GB RAM)
pgptracker process [...] --profile

# Profiles using 'debug' preset (more verbose)
pgptracker analysis [...] --profile debug

A TSV report and a summary table of memory usage per function will be generated after execution.

Citing

PGPTracker is built upon the work of many others. Please cite the core tools and databases it uses. If you use the PGPTracker CLI in your research, please cite:

PGPTracker Software

• Mello, Vivian. PGPTracker: Integration of soil metagenomic data for correlation of microbial markers with plant biochemical indicators. (2025). UFPR Palotina.

PGPTracker & PLaBAse

• Atz, S., Rauh, M., Gautam, A., Huson, D.H. mgPGPT: Metagenomic analysis of plant growth-promoting traits. (submitted, 2024, preprint)
• Patz, S., Gautam, A., Becker, M., Ruppel, S., Rodríguez-Palenzuela, P., Huson, D.H. PLaBAse: A comprehensive web resource for analyzing the plant growth-promoting potential of plant-associated bacteria. (submitted 2021, preprint)

Core Dependencies

• QIIME 2: Bolyen E, Rideout JR, Dillon MR, et al. (2019). Reproducible, interactive, scalable and extensible microbiome data science using QIIME 2. Nature Biotechnology 37: 852–857.
• PICRUSt2: Douglas, G.M., Maffei, V.J., Zaneveld, J.R. et al. (2020). PICRUSt2 for prediction of metagenome functions. Nature Biotechnology 38, 685–688.
• Greengenes2: McDonald, D., et al. (2024). Greengenes2 unifies microbial data in a single reference tree. Nature Biotechnology.