Package 'ShiVa'

Title: Detection of Evolutionary Shifts in Both Optimal Value and Variance
Description: Implements statistical methods for detecting evolutionary shifts in both the optimal trait value (mean) and evolutionary diffusion variance. The method uses an L1-penalized optimization framework to identify branches where shifts occur, and the shift magnitudes. It also supports the inclusion of measurement error. For more details, see Zhang, Ho, and Kenney (2023) <doi:10.48550/arXiv.2312.17480>.
Authors: Wensha Zhang [aut, cre], Lam Si Tung Ho [aut], Toby Kenney [aut]
Maintainer: Wensha Zhang <[email protected]>
License: GPL (>= 3)
Version: 1.1.1
Built: 2026-05-27 10:48:35 UTC
Source: https://github.com/wenshaz/shiva

Help Index

Backward Selection for Shift Correction

Description

Backward Selection for Shift Correction

Usage

backward_correction(
  tree,
  Y,
  alpha,
  sv_mean,
  sv_var,
  criterion = "BIC",
  original_model = NULL,
  measurement_error = FALSE,
  verbose = FALSE
)

Arguments

tree

Phylogenetic tree.
Y

Trait values.
alpha

Selection strength.
sv_mean

Mean shift branches.
sv_var

Variance shift branches.
criterion

"BIC", "mBIC", or "pBIC".
original_model

Optional pre-fitted model.
measurement_error

Logical.
verbose

Logical.

Value

Refined model.

Fit OU Model with Shifts in Mean and Variance

Description

Refit with known shift locations. Uses iterative coordinate descent.

Usage

fit_OU_mean_var(
  tree,
  Y,
  alpha,
  sv_mean,
  sv_var,
  max.steps = 1000,
  t = 0.01,
  thres = 0.01,
  measurement_error = FALSE,
  verbose = FALSE
)

Arguments

tree

Phylogenetic tree.
Y

Trait values.
alpha

Selection strength.
sv_mean

Branch indices with mean shifts.
sv_var

Branch indices with variance shifts.
max.steps

Max iterations. Default 1000.
t

Step size. Default 0.01.
thres

Convergence threshold. Default 0.01.
measurement_error

Logical.
verbose

Print convergence info. Default FALSE.

Value

Fitted model list.

Generate Design Matrix

Description

Constructs a design matrix for a given phylogenetic tree.

Usage

generate_design_matrix(tree, type = "simpX", alpha = 0)

Arguments

tree

A phylogenetic tree of class phylo.
type

A character string: "simpX" or "orgX".
alpha

Selection strength (only for type = "orgX").

Value

A design matrix X.

Estimate Shifts in Mean and Variance (LASSO)

Description

L1-penalised estimation of shifts.

Usage

get_mean_var_shifts(
  Y,
  tree,
  alpha,
  lambda1,
  lambda2,
  max.steps = 1000,
  t = 0.01,
  penalty = "L1",
  thres = 0.01,
  sigma2 = NULL,
  measurement_error = FALSE,
  verbose = FALSE
)

Arguments

Y

Trait values.
tree

Phylogenetic tree.
alpha

Selection strength.
lambda1

Penalty for mean shifts.
lambda2

Penalty for variance shifts.
max.steps

Max iterations.
t

Step size.
penalty

"L1" or "None".
thres

Convergence threshold.
sigma2

Optional initial sigma2.
measurement_error

Logical.
verbose

Print convergence info. Default FALSE.

Value

List with detected shifts and parameter estimates.

Model Selection for Shifts in Mean and Variance

Description

Model Selection for Shifts in Mean and Variance

Usage

get_mean_var_shifts_model_selection(
  Y,
  tree,
  alpha,
  lambda1_list = NULL,
  lambda2_list = exp(1:10 - 6),
  criterion = "BIC",
  max.steps = 300,
  nfolds = 5,
  top_k = 3,
  measurement_error = FALSE,
  verbose = FALSE
)

Arguments

Y

Trait values.
tree

Phylogenetic tree.
alpha

Selection strength.
lambda1_list

Candidate lambda1 values.
lambda2_list

Candidate lambda2 values.
criterion

"BIC", "mBIC", or "pBIC".
max.steps

Max iterations.
nfolds

CV folds.
top_k

Top candidates for backward correction.
measurement_error

Logical.
verbose

Logical. Default FALSE.

Value

List with best_model and score_summary.

OU.vcv

Description

Generate covariance matrix for OU process.

Usage

OU.vcv(tree, alpha)

Arguments

tree

phylogenetic tree
alpha

selection strength

Value

Covariance matrix V.

Plot Method for ShiftModel Objects

Description

Plots a phylogenetic tree with detected shifts highlighted.

Usage

## S3 method for class 'ShiftModel'
plot(x, title = "", ...)

Arguments

x

A ShiftModel object.
title

Plot title.
...

Additional arguments passed to plot.phylo.

Value

No return value (side effect: plot).

Print Method for Summary of ShiftModel

Description

Print Method for Summary of ShiftModel

Usage

## S3 method for class 'summary.ShiftModel'
print(x, ...)

Arguments

x

A summary.ShiftModel object.
...

Unused.

Value

No return value (side effect: console output).

ShiVa: Automatic Shift Detection in Mean and Variance

Description

Detects evolutionary shifts in both optimal trait values and diffusion variance under an Ornstein-Uhlenbeck process. Optionally refits alpha after shift detection.

Usage

ShiVa(
  Y,
  tree,
  alpha = NULL,
  t = 0.01,
  lambda1_list = NULL,
  lambda2_list = exp(1:10 - 6),
  criterion = "BIC",
  max.steps = 300,
  nfolds = 5,
  top_k = 3,
  measurement_error = FALSE,
  refit_alpha = TRUE,
  verbose = FALSE
)

Arguments

Y

Trait values at tips.
tree

Phylogenetic tree of class phylo.
alpha

Selection strength. If NULL, estimated via phylolm.
t

Step size. Default 0.01.
lambda1_list

Candidate lambda1 values.
lambda2_list

Candidate lambda2 values. Default exp(1:10 - 6).
criterion

"BIC", "mBIC", or "pBIC". Default "BIC".
max.steps

Max iterations. Default 300.
nfolds

CV folds. Default 8.
top_k

Top candidates for backward correction. Default 10.
measurement_error

Logical. Default FALSE.
refit_alpha

Logical. If TRUE, refit alpha after detection. Default TRUE.
verbose

Logical. Default FALSE.

Value

List with best_model and score_summary.

Soft Thresholding

Description

Soft Thresholding

Usage

soft_thresholding(z, lambda)

Arguments

z

Numeric value.
lambda

Threshold level.

Value

Thresholded value.

Summary of a ShiVa Shift Model

Description

Summary of detected shifts and fitted parameters.

Usage

## S3 method for class 'ShiftModel'
summary(object, ...)

Arguments

object

A ShiftModel object.
...

Unused.

Value

A summary.ShiftModel object.

Update Step for Gamma

Description

Update Step for Gamma

Usage

update_step_gamma(gamma_k, X_k, Sigma, r, lambda2, t, penalty, V, q_k)

Arguments

gamma_k

Current gamma value.
X_k

Column of design matrix.
Sigma

Current covariance matrix.
r

Residual vector.
lambda2

Penalty parameter.
t

Step size.
penalty

"L1" or "None".
V

Baseline covariance matrix.
q_k

Element of design vector q.

Value

List with updated gamma_k and Sigma.