Tree-Aggregated Classification (trac)

Tree-Aggregated Classification (trac)#

trac (tree-aggregation of compositional data) [C4] places coefficients on nodes of the taxonomy, not only on individual ASVs. Weights derived from the hierarchy make an internal node — a genus, an order, a phylum — competitive with its members, so the fitted classifier can name the clades whose aggregated abundance tracks the split between vegetated and bare sites. A named clade is easier to interpret than the ASVs beneath it, and may classify more accurately.

Step 1: Transform Features#

Apply CLR transformation to the count data:

qiime classo transform-features \
    --p-transformation clr \
    --p-coef 0.5 \
    --i-features data/atacama-counts.qza \
    --o-x data/xclr

Step 2: Add Taxonomic Information#

Attach the taxonomy to the design and derive an adaptive weight for every node:

qiime classo add-taxa \
    --i-features data/xclr.qza  \
    --i-taxa data/classification.qza \
    --o-x data/xtaxa \
    --o-aweights data/wtaxa

The action uses the taxonomic hierarchy to structure the relationships between features and derives each adaptive weight from the taxonomic distances, which encourages the fit to select taxa that share taxonomic relatives.

Step 3: Add Covariates#

Include environmental metadata with custom weights, alongside the taxonomic features:

qiime classo add-covariates \
    --i-features data/xtaxa.qza \
    --i-weights data/wtaxa.qza \
    --m-covariates-file data/atacama-selected-covariates-veg.tsv \
    --p-to-add ph average-soil-relative-humidity elevation average-soil-temperature vegetation \
    --p-w-to-add 1. 0.1 0.1 0.1 1 \
    --o-new-features data/xcovariates_trac \
    --o-new-c data/ccovariates_trac \
    --o-new-w data/wcovariates_trac

Step 4: Split Data#

Create training and test sets for classification analysis:

qiime sample-classifier split-table \
    --i-table data/xcovariates_trac.qza \
    --m-metadata-file data/atacama-selected-covariates-veg.tsv \
    --m-metadata-column vegetation \
    --p-test-size 0.2 \
    --p-random-state 42 \
    --p-stratify False \
    --o-training-table data/classify-xtraining_trac.qza \
    --o-test-table data/classify-xtest_trac.qza \
    --o-training-targets data/classify-training-targets_trac.qza \
    --o-test-targets data/classify-test-targets_trac.qza

Step 5: Train the Classification Model#

Fit the classifier on the aggregated design:

qiime classo classify \
    --i-features data/classify-xtraining_trac.qza \
    --i-c data/ccovariates_trac.qza \
    --i-weights data/wcovariates_trac.qza \
    --m-y-file data/atacama-selected-covariates-veg.tsv \
    --m-y-column vegetation \
    --p-huber False \
    --p-stabsel \
    --p-cv \
    --p-path \
    --p-lamfixed \
    --p-stabsel-threshold 0.5 \
    --p-cv-seed 42 \
    --p-no-cv-one-se \
    --o-result data/classifytaxa_trac.qza

Parameters explained:

  • --i-features: Training feature table

  • --i-c: C matrix carrying the log-contrast constraints

  • --i-weights: Feature weights, taxonomic weights included

  • --m-y-column vegetation: Target variable

  • --p-huber False: Use standard logistic loss

  • --p-stabsel: Run stability selection alongside the path fit

  • --p-cv: Choose the penalty by cross-validation

  • --p-stabsel-threshold 0.5: Stability selection threshold

Step 6: Make Predictions#

Apply the trained model to test data:

qiime classo predict \
    --i-features data/classify-xtest_trac.qza \
    --i-problem data/classifytaxa_trac.qza \
    --o-predictions data/classify-predictions_trac.qza

Step 7: Generate Summary Visualization#

Render the fit, the taxonomy and the predictions as a single report:

qiime classo summarize \
    --i-problem data/classifytaxa_trac.qza \
    --i-taxa data/classification.qza \
    --i-predictions data/classify-predictions_trac.qza \
    --o-visualization data/classifytaxa_C1_trac.qzv

The .qzv file contains:

  • the selected taxa with their taxonomic context

  • model performance metrics (accuracy, precision, recall, F1-score)

  • taxonomic group importances

  • a confusion matrix for the test predictions

  • cross-validation curves

View the results at QIIME 2 View.

Log-contrast and trac side by side#

Log-contrast treats each taxon as an independent predictor, fits faster, and suits exploratory work.

trac uses the taxonomic relationships, reports coefficients on named clades, selects features better when the structure is hierarchical, and takes somewhat longer to fit.