Phylogenetic regression (PGLS)

Phylogenetic generalized least squares regression (supports discordance-aware VCV with -g)

Command identity

Canonical command:

phylogenetic_regression

Handler:

phylogenetic_regression

Aliases:

pgls, phylo_regression

Standalone executables:

pk_phylogenetic_regression, pk_pgls, pk_phylo_regression

Categories:

Phylogenetic comparative methods

Runtime interface

Synopsis

phykit phylogenetic_regression --tree <tree> --trait_data <trait_data> --response <response> --predictors <predictors> [--method <method>] [--gene-trees <gene_trees>] [--json]

Arguments

This table is generated from the live command parser. It is the authoritative source for accepted spellings, required arguments, types, defaults, and choices.

Argument	Required	Type	Default	Choices
-t, --tree	true	str	required	any
-d, --trait_data	true	str	required	any
-y, --response	true	str	required	any
-x, --predictors	true	str	required	any
-m, --method	false	str	BM	BM, lambda
-g, --gene-trees	false	str	none	any
--json	false	boolean	false	any

Output and errors

--json provides the command's structured JSON representation. Unless the guidance below states otherwise, results are emitted as command output. Invalid command syntax exits with status 2. Input validation and scientific limitations are described in the guidance below.

Guidance, interpretation, and examples

Fit a Phylogenetic Generalized Least Squares (PGLS) regression while accounting for phylogenetic non-independence among species, analogous to R's caper::pgls().

The multi-trait input file should be tab-delimited with a header row: taxon<tab>trait1<tab>trait2<tab>... Lines starting with '#' are treated as comments. If the tree and trait file have different taxa, the intersection is used and warnings are printed to stderr.

Two methods are available:

• BM (default): Brownian motion with lambda fixed at 1

• lambda: jointly estimates Pagel's lambda via maximum likelihood

Output includes coefficient estimates, standard errors, t-values, p-values, R-squared, adjusted R-squared, F-statistic, log-likelihood, and AIC.

A three-way variance decomposition is also reported: R²_total (variance explained by phylogeny + predictors combined), R²_pred (predictor contribution given phylogeny, = standard R²), and R²_phylo (phylogeny's unique contribution). R²_phylo + R²_pred = R²_total.

The implementation uses the raw phylogenetic variance-covariance (VCV) matrix for GLS estimation, matching the approach used by R's caper::pgls(). Note that this differs from nlme::gls() with corBrownian, which normalizes the VCV to a correlation matrix (ones on the diagonal). For non-ultrametric trees the two approaches yield different coefficient estimates; PhyKIT follows the caper convention.

All results have been validated against R 4.4.0 using manual GLS with ape::vcv() (raw VCV). Coefficients, standard errors, t-values, p-values, R-squared, F-statistic, log-likelihood, and AIC match R to at least four decimal places for both simple and multiple regression.

phykit phylogenetic_regression -t <tree> -d <trait_data> -y <response> -x <predictor1> [predictor2 ...] [-m <method>] [-g <gene_trees>] [--json]

Options:
-t/--tree: a tree file in Newick format
-d/--trait_data: tab-delimited multi-trait file with header row
-y/--response: response (dependent) variable column name
-x/--predictors: one or more predictor column names
-m/--method: method to use: BM or lambda (default: BM)
-g/--gene-trees: optional multi-Newick file of gene trees; when provided, uses a discordance-aware VCV (genome-wide average) instead of the species-tree VCV
--json: optional argument to print results as JSON

R validation: Validated against caper, nlme in R (see tests/r_validation/validate_pgls_r2.R).