get_mean_var_shifts_model_selection: 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
)

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.

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.