get_mean_var_shifts_model_selection: Model Selection for OU Shifts in Optimal value and Variance

In ShiVa: Detection of Evolutionary Shifts in Both Optimal Value and Variance

Model Selection for OU Shifts in Optimal value and Variance

Description

Performs model selection to estimate the locations and magnitudes of evolutionary shifts in optimal trait values (mean) and diffusion variance under an Ornstein-Uhlenbeck (OU) process. This function searches across user-defined grids of shrinkage parameters for both types of shifts, uses cross-validation for selecting lambda1, and applies backward correction to refine top candidate models.

Usage

get_mean_var_shifts_model_selection(
  Y,
  tree,
  alpha,
  t = 0.01,
  lambda1_list = NULL,
  lambda2_list = exp(1:10 * 0.4 - 6),
  criterion = "BIC",
  max.steps = 300,
  nfolds = 8,
  top_k = 10,
  measurement_error = FALSE,
  lambda.type = "lambda.1se",
  max.num.shifts = Inf,
  verbose = TRUE
)

Arguments

Y	A numeric vector of trait values for the species at the tips of the phylogenetic tree.
tree	A phylogenetic tree of class phylo.
alpha	A non-negative numeric value representing the selection strength in the OU process.
t	Step size for iterative optimization. Default is 0.01.
lambda1_list	A numeric vector of candidate \lambda_1 values controlling shrinkage for shifts in optimal values.
lambda2_list	A numeric vector of candidate \lambda_2 values controlling shrinkage for shifts in variance. Default is exp(1:10*0.4-6)
criterion	Model selection criterion to optimize. Options include "BIC", "mBIC", or "pBIC". Default is "BIC".
max.steps	Maximum number of optimization steps. Default is 300.
nfolds	Number of cross-validation folds for tuning lambda1. Default is 8.
top_k	Number of top candidate models (ranked by criterion) to further refine using backward correction. Default is 10.
measurement_error	Logical. If TRUE, estimates a separate measurement error variance component. Default is FALSE.
lambda.type	A character string specifying the cross-validation rule used to select lambda1 from lambda1_list. Options are "lambda.min" (minimum CV error) and "lambda.1se" (1-SE rule, higher penalty). Default is "lambda.1se".
max.num.shifts	An integer specifying the maximum number of allowed shifts (combined across mean and variance). Default is Inf.
verbose	Logical. If TRUE, prints progress messages to the console. Default is TRUE.

Value

A list containing:

best_model	The final selected OU model object, with estimated shifts and parameters.
score_summary	A data frame summarizing the model selection results, including pre- and post-correction scores and shift locations.

ShiVa documentation built on Aug. 22, 2025, 9:14 a.m.