R: *cov*ariance matrix for survival data

COV {survMisc} | R Documentation

## covariance matrix for survival data

### Description

covariance matrix for survival data

### Usage

    COV(x, ...)

    ## S3 method for class 'ten'
    COV(x, ..., reCalc = FALSE)

    ## S3 method for class 'stratTen'
    COV(x, ..., reCalc = FALSE)

    ## S3 method for class 'numeric'
    COV(x, ..., n, ncg)

### Arguments

`x` | A `numeric` vector of number of events, e[t]. These are assumed to be ordered by discrete times. A method is available for objects of `class` `ten`.
`...` | Additional arguments (not implemented).
`reCalc` | Recalcuate the values? If `reCalc=FALSE` (the default) and the `ten` object already has the calculated values stored as an `attribute`, the value of the `attribute` is returned directly. –Arguments for the numeric method:
`n` | number at risk (total).
`ncg` | number at risk, per covariate group. If there are 2 groups, this can be given as a `vector` with the number at risk for group 1. If there are >= 2 groups, it is a `matrix` with one column for each group.

### Details

Gives variance-covariance matrix for comparing survival data for two or more groups.
Inputs are vectors corresponding to observations at a set of discrete time points for right censored data, except for n1, the no. at risk by predictor.
This should be specified as a vector for one group, otherwise as a matrix with each column corresponding to a group.

### Value

An `array`.
The first two dimensions = the number of covariate groups K, k = 1, 2, … K. This is the square matrix below.
The third dimension is the number of observations (discrete time points).
To calculate this, we use `x` (= e[t] below) and n1, the number at risk in covariate group 1.
Where there are 2 groups, the resulting sparse square matrix (i.e. the non-diagonal elements are 0) at time t has diagonal elements:

cov[t] = - n0[t] * n1[t] * e[t] * (n[t] - e[t]) / (n[t]^2 * (n[t] - 1))

For >=2 groups, the resulting square matrix has diagonal elements given by:

cov[k, k, t] = n[k, t] * (n[t] - n[k, t]) * e[t] * (n[t] - e[t]) / (n[t]^2 * (n[t] - 1))

The off diagonal elements are:

cov[k, l, t] = - n[k, t] * n[l, t] * e[t] * (n[t] - e[t]) / n[t]^2 * (n[t] - 1)

### Note

Where the is just one subject at risk n=1 at the final timepoint, the equations above may produce `NaN` due to division by zero. This is converted to `0` for simplicity.

### See Also

Called by `comp`

The name of the function is capitalized to distinguish it from:
?stats::cov

### Examples

    ## Two covariate groups
    ## K&M. Example 7.2, pg 210, table 7.2 (last column).
    ## Not run:
    data("kidney", package="KMsurv")
    k1 <- with(kidney,
               ten(Surv(time=time, event=delta) ~ type))
    COV(k1)[COV(k1) > 0]

    ## End(Not run)
    ## Four covariate groups
    ## K&M. Example 7.6, pg 217.
    ## Not run:
    data("larynx", package="KMsurv")
    l1 <- ten(Surv(time, delta) ~ stage, data=larynx)
    rowSums(COV(l1), dims=2)

    ## End(Not run)
    ## example of numeric method
    ## Three covariate groups
    ## K&M. Example 7.4, pg 212.
    ## Not run:
    data("bmt", package="KMsurv")
    b1 <- asWide(ten(Surv(time=t2, event=d3) ~ group, data=bmt))
    rowSums(b1[, COV(x=e, n=n, ncg=matrix(data=c(n_1, n_2, n_3), ncol=3))], dims=2)

    ## End(Not run)

[Package survMisc version 0.5.4 Index]