Phylogenetic GLM

Phylogenetic generalized linear model (supports discordance-aware VCV with -g)

Command identity

Canonical command:

phylogenetic_glm

Handler:

phylogenetic_glm

Aliases:

pglm, phylo_glm

Standalone executables:

pk_phylogenetic_glm, pk_pglm, pk_phylo_glm

Categories:

Phylogenetic comparative methods

Runtime interface

Synopsis

phykit phylogenetic_glm --tree <tree> --trait_data <trait_data> --response <response> --predictors <predictors> --family <family> [--method <method>] [--btol <btol>] [--log-alpha-bound <log_alpha_bound>] [--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
--family	true	str	required	binomial, poisson
--method	false	str	none	logistic_MPLE, poisson_GEE
--btol	false	float	10	any
--log-alpha-bound	false	float	4	any
-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 Linear Model (GLM) for binary or count response data while accounting for phylogenetic non-independence among species.

Two families are supported:

• binomial: logistic regression via Maximum Penalized Likelihood Estimation (logistic_MPLE; Ives & Garland 2010). Uses Firth's penalty to prevent bias from complete/quasi-complete separation, and jointly estimates the phylogenetic signal parameter alpha via a two-state continuous-time Markov chain on the tree.

• poisson: Poisson regression via Generalized Estimating Equations (poisson_GEE; Paradis & Claude 2002). Uses Fisher scoring with the phylogenetic correlation matrix and reports an overdispersion parameter.

The multi-trait input file should be tab-delimited with a header row: taxon<tab>trait1<tab>trait2<tab>...

Output includes coefficient estimates, standard errors, z-values, p-values, log-likelihood, AIC, and McFadden's pseudo-R² (computed from full vs. intercept-only model log-likelihoods).

phykit phylogenetic_glm -t <tree> -d <trait_data> -y <response> -x <predictor1> [predictor2 ...] --family <binomial|poisson> [-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
--family: distribution family: binomial or poisson
--method: estimation method: logistic_MPLE or poisson_GEE (auto from family)
--btol: linear predictor bound for logistic model (default: 10)
--log-alpha-bound: bound on log(alpha) for logistic model (default: 4)
-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 phylolm in R (see tests/r_validation/validate_glm_pseudo_r2.R).