Test a Clade Matrix for association with phenotypes

Test a local phylogeny for association with phenotypes based on a matrix prodced by kalis::CladesMat

Usage

TestCladeMat(
  y,
  M,
  Q,
  k = NULL,
  prop.var.goal = 0.95,
  var.ratio.goal = 0.95,
  stop.eval.func = NULL,
  calc.obs.T = FALSE,
  use.forking = FALSE,
  nthreads = 1L
)

Arguments

y

a matrix of phenotypes

M

a matrix as produced by kalis::CladesMat

Q

an orthogonal matrix whose columns span the column space of the background covariates

k

a vector of non-negative integers, number of eigenvalues to calculate to try to approximate the null distribution, see Details.

var.ratio.goal

a double in [0,1], if lambda_k / lambda_k-1 >= var.ratio.goal, the spectrum has plateaued, then we can trust our approximation and stop calculating eigenvalues, see Details.

stop.eval.func

a function that returns TRUE if all associations can be ruled insignificant and eigendecomposition stopped early, see Details.

use.forking

a logical, should forking be used during underlying FFT?

nthreads

a positive integer, how many cores in multithreaded routines?

min.prop.var

a double in [0,1], if we've obtained enough eigenvalues to explain at least this minimum proportion of variance, then we can trust our approximation and stop calculating eigenvalues, see Details.

cs.approx

a logical, should a difference of chi-squares be used to try to approximate remainder or should all of the remainder be left to a Gaussian approximation (the default)

Value

With with p-values for Clade Testing

Details

Concerning the specification of k, k=0 represents evaluating no eigenvalues and simply calculating the Satterthwaite (SW) approximation based on the traces of the matrix. If k is NULL, k is set to 0. If the k provided does not include 0, 0 is appended to k so the SW approximation is always calculated. stop.eval.function is a function that can be used to prematurely stop the procedure if the results are almost guaranteed to be insignificant. This function is called after each number of k eigenvalues is calculated (including after k=0). It always takes one or two arguments. The first argument must always be a vector of estimated QForm p-values in [0,1]. If a second argument is given in the function definition, the proportion of variance explained by the current set of evaluated eigenvalues (a number in [0,1]) will be passed to it. This allows the user to use different early stopping rules based on the p-values of other test statistics, the current estimated set of QForm p-values, and the proportion of variance captured by the current set of eigenvalues. This allows the user to do an initial screen with just the SW approximation (leaving k and stop.eval.func as NULL). If we always want to bipass the SW approximation and try more accurate approximations, we can define stop.eval.func to return FALSE whenever the second argument (prop.var) is 0.

See also

Clades to generate kalisClades object

Examples

if (FALSE) { # \dontrun{
} # }