Fit Independent Post-hoc Regime Covariance Models — fit_regime

Fit separate mvMORPH::mvgls() Brownian-motion models to the tips assigned to each contemporary mapped regime. This is a post-hoc workflow: it estimates independent regime covariance matrices after a mapped-regime analysis has already been chosen.

Usage

fit_regime_covariances(
  x = NULL,
  tree = NULL,
  trait_data,
  formula = trait_data ~ 1,
  model = "BM",
  min_tips = 2L,
  cores = 1L,
  error = TRUE,
  ...
)

Arguments

x: Optional bifrost_search object, compatible list with a tree_no_uncertainty_untransformed component, or SIMMAP-style phylo tree. If tree is supplied, x is only used as an optional source of regime-rate parameters.
tree: Optional SIMMAP-style phylo tree with mapped states, non-empty regime-state identifiers, and unique, non-empty tip labels. Required when x is NULL.
trait_data: Matrix or data frame with unique, non-empty row names matching the tree tip labels. Column names may be omitted; when present, they must also be unique and non-empty.
formula: Formula used for each regime-specific mvgls() fit. The default treats trait_data as the multivariate response. Formulae may refer to trait_data directly, as in trait_data[, 1:5] ~ trait_data[, 6], or to columns by name.
model: Evolutionary model passed to mvMORPH::mvgls(). The default "BM" matches the independent post-hoc covariance workflow.
min_tips: Minimum number of tips required before a regime is fitted. Regimes are fitted when tip_count >= min_tips; regimes with fewer tips are returned with status "skipped". The default of two tips matches the Berv et al. post-hoc fitting script.
cores: Number of workers. Values greater than one use future.apply::future_lapply() with a temporary multisession plan.
error: Logical passed to mvMORPH::mvgls().
...: Additional arguments passed to mvMORPH::mvgls().

Value

An object of class regime_covariances, a list with:

fits: Named list of regime-specific mvgls fits or NULL.
covariances: Named list of extracted post-hoc covariance matrices or NULL for skipped/failed regimes.
status: Data frame with regime ID, tip count, regime age, status, and message.
rates: Named regime-rate vector if available from x; otherwise NULL.

Details

The covariance matrices returned here are independent post-hoc estimates. They are not the same object as search$VCVs in a bifrost_search result: the current bifrost search model uses scalar transformations of a shared phenotypic covariance matrix, so search$VCVs are proportional joint-model matrices rather than independently refit regime matrices. Extracted matrices must be symmetric and positive semidefinite, contain finite entries and strictly positive diagonal variances, and, when named, have unique matching row and column trait names. Fits that do not satisfy those requirements are retained with status "failed" and a diagnostic message.