coxmeg_m {coxmeg}R Documentation

Fit a Cox mixed-effects model for estimating HRs for a set of predictors

Description

coxmeg_m first estimates the variance component under a null model with only cov, and then analyzing each predictor in X one by one.

Usage

coxmeg_m(X, outcome, corr, type, FID = NULL, cov = NULL, tau = NULL,
  min_tau = 1e-04, max_tau = 5, eps = 1e-06, order = NULL,
  detap = NULL, opt = "bobyqa", score = FALSE, threshold = 0,
  solver = NULL, spd = TRUE, verbose = TRUE, mc = 100)

Arguments

X

A matrix of the preidctors. Can be quantitative or binary values. Categorical variables need to be converted to dummy variables. Each row is a sample, and the predictors are columns.

outcome

A matrix contains time (first column) and status (second column). The status is a binary variable (1 for failure / 0 for censored).

corr

A relatedness matrix. Can be a matrix or a 'dgCMatrix' class in the Matrix package. Must be symmetric positive definite or symmetric positive semidefinite.

type

A string indicating the sparsity structure of the relatedness matrix. Should be 'bd' (block diagonal), 'sparse', or 'dense'. See details.

FID

An optional string vector of family ID. If provided, the data will be reordered according to the family ID.

cov

An optional matrix of the covariates included in the null model for estimating the variance component. Can be quantitative or binary values. Categorical variables need to be converted to dummy variables. Each row is a sample, and the covariates are columns.

tau

An optional positive value for the variance component. If tau is given, the function will skip estimating the variance component, and use the given tau to analyze the predictors.

min_tau

An optional positive value indicating the lower bound in the optimization algorithm for the variance component tau. Default is 1e-4.

max_tau

An optional positive value indicating the upper bound in the optimization algorithm for the variance component tau. Default is 5.

eps

An optional positive value indicating the tolerance in the optimization algorithm. Default is 1e-6.

order

An optional integer value starting from 0. Only valid when dense=FALSE. It specifies the order of approximation used in the inexact newton method. Default is NULL, which lets coxmeg choose an optimal order.

detap

An optional string indicating whether to use approximation for log-determinant. Can be 'exact', 'diagonal' or 'slq'. Default is NULL, which lets the function select a method based on 'type' and other information. See details.

opt

An optional logical value for the Optimization algorithm for tau. Can have the following values: 'bobyqa', 'Brent' or 'NM'. Default is 'bobyqa'.

score

An optional logical value indicating whether to perform a score test. Default is FALSE.

threshold

An optional non-negative value. If threshold>0, coxmeg_m will reestimate HRs for those SNPs with a p-value<threshold by first estimating a variant-specific variance component. Default is 0.

solver

An optional bianry value that can be either 1 (Cholesky Decomposition using RcppEigen), 2 (PCG) or 3 (Cholesky Decomposition using Matrix). Default is NULL, which lets the function select a solver. See details.

spd

An optional logical value indicating whether the relatedness matrix is symmetric positive definite. Default is TRUE. See details.

verbose

An optional logical value indicating whether to print additional messages. Default is TRUE.

mc

An optional integer value specifying the number of Monte Carlo samples used for approximating the log-determinant. Only valid when dense=TRUE and detap='slq'. Default is 100.

Value

beta: The estimated coefficient for each predictor in X.

HR: The estimated HR for each predictor in X.

sd_beta: The estimated standard error of beta.

p: The p-value of each SNP.

tau: The estimated variance component.

iter: The number of iterations until convergence.

About type

'bd' is used for a block-diagonal relatedness matrix, or a sparse matrix the inverse of which is also sparse. 'sparse' is used for a general sparse relatedness matrix the inverse of which is not sparse.

About spd

When spd=TRUE, the relatedness matrix is treated as SPD. If the matrix is SPSD or not sure, use spd=FALSE.

About solver

When solver=1,3/solver=2, Cholesky decompositon/PCG is used to solve the linear system. When solver=3, the solve function in the Matrix package is used, and when solver=1, it uses RcppEigen:LDLT to solve linear systems. When type='dense', it is recommended to set solver=2 to have better computational performance.

About detap

When detap='exact', the exact log-determinant is computed for estimating the variance component. Specifying detap='diagonal' uses diagonal approximation, and is only effective for a sparse relatedness matrix. Specifying detap='slq' uses stochastic lanczos quadrature approximation.

Examples

library(Matrix)
library(MASS)
library(coxmeg)

## simulate a block-diagonal relatedness matrix
tau_var <- 0.2
n_f <- 100
mat_list <- list()
size <- rep(10,n_f)
offd <- 0.5
for(i in 1:n_f)
{
  mat_list[[i]] <- matrix(offd,size[i],size[i])
  diag(mat_list[[i]]) <- 1
}
sigma <- as.matrix(bdiag(mat_list))
n <- nrow(sigma)

## simulate random effects and outcomes
x <- mvrnorm(1, rep(0,n), tau_var*sigma)
myrates <- exp(x-1)
y <- rexp(n, rate = myrates)
cen <- rexp(n, rate = 0.02 )
ycen <- pmin(y, cen)
outcome <- cbind(ycen,as.numeric(y <= cen))

## simulate genotypes
g = matrix(rbinom(n*5,2,0.5),n,5)

## The following command will first estimate the variance component without g, 
## and then use it to estimate the HR for each preditor in g.
re = coxmeg_m(g,outcome,sigma,type='bd',tau=0.5,detap='diagonal',order=1)
re

[Package coxmeg version 1.0.12 Index]