NAG Library Function Document
nag_surviv_cox_model (g12bac)
1
Purpose
nag_surviv_cox_model (g12bac) returns parameter estimates and other statistics that are associated with the Cox proportional hazards model for fixed covariates.
2
Specification
#include <nag.h> |
#include <nagg12.h> |
void |
nag_surviv_cox_model (Integer n,
Integer m,
Integer ns,
const double z[],
Integer tdz,
const Integer sz[],
Integer ip,
const double t[],
const Integer ic[],
const double omega[],
const Integer isi[],
double *dev,
double b[],
double se[],
double sc[],
double cov[],
double res[],
Integer *nd,
double tp[],
double sur[],
Integer tdsur,
Integer ndmax,
double tol,
Integer max_iter,
Integer iprint,
const char *outfile,
NagError *fail) |
|
3
Description
The proportional hazard model relates the time to an event, usually death or failure, to a number of explanatory variables known as covariates. Some of the observations may be right censored, that is the exact time to failure is not known, only that it is greater than a known time.
Let
, for
be the failure time or censored time for the
th observation with the vector of
covariates
. It is assumed that censoring and failure mechanisms are independent. The hazard function,
, is the probability that an individual with covariates
fails at time
given that the individual survived up to time
. In the Cox proportional hazards model (
Cox (1972))
is of the form:
where
is the base-line hazard function, an unspecified function of time,
is a vector of unknown arguments and
is a known offset.
Assuming there are ties in the failure times giving
distinct failure times,
such that
individuals fail at
, it follows that the marginal likelihood for
is well approximated (see
Kalbfleisch and Prentice (1980)) by:
where
is the sum of the covariates of individuals observed to fail at
and
is the set of individuals at risk just prior to
, that is it is all individuals that fail or are censored at time
along with all individuals that survive beyond time
. The maximum likelihood estimates (MLEs) of
, given by
, are obtained by maximizing
(1) using a Newton–Raphson iteration technique that includes step halving and utilizes the first and second partial derivatives of
(1) which are given by equations
(2) and
(3) below:
for
, where
is the
th element in the vector
and
Similarly,
where
is the
th component of a score vector and
is the
element of the observed information matrix
whose inverse
gives the variance-covariance matrix of
.
It should be noted that if a covariate or a linear combination of covariates is monotonically increasing or decreasing with time then one or more of the 's will be infinite.
If
varies across
strata, where the number of individuals in the
th stratum is
,
with
, then rather than maximizing
(1) to obtain
, the following marginal likelihood is maximized:
where
is the contribution to likelihood for the
observations in the
th stratum treated as a single sample in
(1). When strata are included the covariate coefficients are constant across strata but there is a different base-line hazard function
.
The base-line survivor function associated with a failure time
, is estimated as
, where
where
is the number of failures at time
. The residual for the
th observation is computed as:
where
. The deviance is defined as
(logarithm of marginal likelihood). There are two ways to test whether individual covariates are significant: the differences between the deviances of nested models can be compared with the appropriate
-distribution; or, the asymptotic normality of the parameter estimates can be used to form
tests by dividing the estimates by their standard errors or the score function for the model under the null hypothesis can be used to form
tests.
4
References
Cox D R (1972) Regression models in life tables (with discussion) J. Roy. Statist. Soc. Ser. B 34 187–220
Gross A J and Clark V A (1975) Survival Distributions: Reliability Applications in the Biomedical Sciences Wiley
Kalbfleisch J D and Prentice R L (1980) The Statistical Analysis of Failure Time Data Wiley
5
Arguments
- 1:
– IntegerInput
-
On entry: the number of data points, .
Constraint:
.
- 2:
– IntegerInput
-
On entry: the number of covariates in array
z.
Constraint:
.
- 3:
– IntegerInput
-
On entry: the number of strata. If
then the stratum for each observation must be supplied in
isi.
Constraint:
.
- 4:
– const doubleInput
-
Note: the th element of the matrix is stored in .
On entry: the
th row must contain the covariates which are associated with the
th failure time given in
t.
- 5:
– IntegerInput
-
On entry: the stride separating matrix column elements in the array
z.
Constraint:
.
- 6:
– const IntegerInput
-
On entry: indicates which subset of covariates is to be included in the model.
- The th covariate is included in the model.
- The th covariate is excluded from the model and not referenced.
Constraints:
- ;
- At least one and at most elements of sz must be nonzero where is the number of observations excluding any with zero value of isi.
- 7:
– IntegerInput
-
On entry: the number of covariates included in the model as indicated by
sz.
Constraint:
number of nonzero values of
sz.
- 8:
– const doubleInput
-
On entry: the vector of failure censoring times.
- 9:
– const IntegerInput
-
On entry: the status of the individual at time
given in
t.
- Indicates that the th individual has failed at time .
- Indicates that the th individual has been censored at time .
Constraint:
, for .
- 10:
– const doubleInput
-
On entry: if an offset is required then
omega must contain the value of
, for
. Otherwise
omega must be set
NULL.
- 11:
– const IntegerInput
-
On entry: if
the stratum indicators which also allow data points to be excluded from the analysis. If
,
isi is not referenced and may be
NULL.
- Indicates that the th data point is in the th stratum, for .
- Indicates that the th data point is omitted from the analysis.
Constraint:
if
,
, and more than
ip values of
, for
.
- 12:
– double *Output
-
On exit: the deviance, that is (maximized log marginal likelihood).
- 13:
– doubleInput/Output
-
On entry: initial estimates of the covariate coefficient arguments
.
must contain the initial estimate of the coefficient of the covariate in
z corresponding to the
th nonzero value of
sz.
Suggested value:
In many cases an initial value of zero for
may be used. For other suggestions see
Section 9.
On exit:
contains the estimate
, the coefficient of the covariate stored in the
th column of
z where
is the
th nonzero value in the array
sz.
- 14:
– doubleOutput
-
On exit: is the asymptotic standard error of the estimate contained in and score function in for .
- 15:
– doubleOutput
-
On exit: is the value of the score function, , for the estimate contained in .
- 16:
– doubleOutput
-
On exit: the variance-covariance matrix of the parameter estimates in
b stored in packed form by column, i.e., the covariance between the parameter estimates given in
and
,
, is stored in
.
- 17:
– doubleOutput
-
On exit: the residuals, , .
- 18:
– Integer *Output
-
On exit: the number of distinct failure times.
- 19:
– doubleOutput
-
On exit: contains the th distinct failure time, for .
- 20:
– doubleOutput
-
Note: the th element of the matrix is stored in .
On exit: if
,
sur contains the estimated survival function for the
th distinct failure time.
If
,
sur contains the estimated survival function for the
th distinct failure time in the
th stratum.
- 21:
– IntegerInput
-
On entry: the stride separating matrix column elements in the array
sur.
Constraint:
.
- 22:
– IntegerInput
-
On entry: the
second
dimension of the array
sur.
Constraint:
the number of distinct failure times. This is returned in
nd.
- 23:
– doubleInput
-
On entry: indicates the accuracy required for the estimation. Convergence is assumed when the decrease in deviance is less than (CurrentDeviance). This corresponds approximately to an absolute precision if the deviance is small and a relative precision if the deviance is large.
Constraint:
.
- 24:
– IntegerInput
-
On entry: the maximum number of iterations to be used for computing the estimates. If
max_iter is set to 0 then the standard errors, score functions, variance-covariance matrix and the survival function are computed for the input value of
in
b but
is not updated.
Constraint:
.
- 25:
– IntegerInput
-
On entry: indicates if the printing of information on the iterations is required.
- There is no printing.
- The deviance and the current estimates are printed every iprint iterations.
- 26:
– const char *Input
-
On entry: the name of the file into which information is to be output. If
outfile is set to
NULL or to the string ‘stdout’, then the monitoring information is output to
stdout.
- 27:
– NagError *Input/Output
-
The NAG error argument (see
Section 3.7 in How to Use the NAG Library and its Documentation).
6
Error Indicators and Warnings
- NE_2_INT_ARG_LT
-
On entry, while . These arguments must satisfy .
On entry, while . These arguments must satisfy .
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
- NE_ARRAY_CONS
-
The contents of array
ic are not valid.
Constraint: not all values of
ic can be 1.
- NE_G12BA_CONV
-
Convergence has not been achieved in
max_iter iterations. The progress towards convergence can be examined by using by setting
iprint to
. Any non-convergence may be due to a linear combination of covariates being monotonic with time. Full results are returned.
- NE_G12BA_DEV
-
In the current iteration 10 step halvings have been performed without decreasing the deviance from the previous iteration. Convergence is assumed.
- NE_G12BA_MAT_SING
-
The matrix of second partial derivatives is singular. Try different starting values or include fewer covariates.
- NE_G12BA_NDMAX
-
On entry,
ndmax is
while the output value of
.
Constraint:
.
- NE_G12BA_OVERFLOW
-
Overflow has been detected. Try different starting values.
- NE_G12BA_SZ_IP
-
On entry,
and the number of nonzero values of
.
Constraint:
the number of nonzero values of
sz.
- NE_G12BA_SZ_ISI
-
On entry, the number of values of
is
,
and excluded observations with
is
.
Constraint: the number of values of nonzero
sz must be less than
excluded observations.
- NE_INT_ARG_LT
-
On entry, .
Constraint: .
On entry,
max_iter must not be less than 0:
.
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_ARRAY_CONS
-
On entry, .
Constraint: or 1.
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INTERNAL_ERROR
-
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact
NAG for assistance.
- NE_NOT_APPEND_FILE
-
Cannot open file
outfile for appending.
- NE_NOT_CLOSE_FILE
-
Cannot close file
outfile.
- NE_REAL_MACH_PREC
-
On entry, , .
Constraint: .
7
Accuracy
The accuracy is specified by
tol.
8
Parallelism and Performance
nag_surviv_cox_model (g12bac) is not threaded in any implementation.
nag_surviv_cox_model (g12bac) uses mean centering which involves subtracting the means from the covariables prior to computation of any statistics. This helps to minimize the effect of outlying observations and accelerates convergence.
If the initial estimates are poor then there may be a problem with overflow in calculating
or there may be non-convergence. Reasonable estimates can often be obtained by fitting an exponential model using
nag_glm_poisson (g02gcc).
10
Example
The data are the remission times for two groups of leukemia patients (see
Gross and Clark (1975) p242). A dummy variable indicates which group they come from. An initial estimate is computed using the exponential model and then the Cox proportional hazard model is fitted and parameter estimates and the survival function are printed.
10.1
Program Text
Program Text (g12bace.c)
10.2
Program Data
Program Data (g12bace.d)
10.3
Program Results
Program Results (g12bace.r)