Aalen's additive regression model:
Contents:
This is a package of S-plus functions which perform additive survival analysis. The project of creating the package was funded by the Norwegian Cancer Society. The package can be used with success in other forms of research both within and outside the medical field.
The routines are free, and we will like you to share it with others, but remember to pass on this documentation. Also note that as this package is free, it COMES WITH ABSOLUTELY NO WARRANTY, REGARDING THE METHOD, ITS IMPLEMENTATION AND ITS DOCUMENTATION. In addition we can not give any technical support, but would like comments and feedback on how the functions works.
All the functions are written at Section of Medical Statistics, University of Oslo, Norway by Harald Fekjær, with theoretical help from Prof. Odd Aalen.
For comments please e-mail us on "hfe@math.uio.no" . On-line documentation is also available on internet; "http://www.med.uio.no/imb/stat/addreg/"
The additive regression is an alternative (or supplement) to the Cox model. It results in plots that are informative regarding the effect of covariates on survival.
Assume that one observes the possibly censored life times of a number of individuals. Let
denote
the hazard rate of individual i, n the number of individuals and
r the number of covariates in the analysis. Consider the column vector
of
hazard rates
,i
= 1,...,n.
The additive model is given by
where
the n
(r+1) matrix
is
constructed as follows: If the ith individual is a member of the risk
set at time t, then the ith row of
is
the vector
where
,j = 1,...,r are, possibly time-varying, covariate values. If the
ith individual is not in the risk set at time t, then the
corresponding row of
contains only zeros.
The vector
,
contains the regression information: The first element is a baseline function;
while the remaining elements, called regression functions, measure the influence of the respective covariates. These
functions are allowed to vary freely over time.
It is easiest to estimate the cumulative regression functions defined by
.
Let
be the column vector with elements
,
j = 0,...,r. This is estimated by an approach which is similar to that
for ordinary linear models, resulting in the following estimator:
Here
are the ordered event times, while
is a column vector consisting of zeros except for a one in the place corresponding to the subject who experiences an event at time
.
The estimator is only defined over the time interval where
has full rank. The matrix
is a generalized inverse of
and
will normally be defined by the ordinary least squares inverse:
The components of
are
to be plotted against time and give information about effects of covariates.
Notice that the regression functions are the derivatives of the cumulative
functions, and so it is the slopes of the plots that are informative.
For further information on the methodology, see the references below:
Aalen, O.O. (1989). A linear regression model for the analysis of life times. Statistics in Medicine 8 907-925.
Aalen, O.O. (1993). Further results on the non - parametric linear regression
model in survival analysis. Statistics in Medicine 12 1569-1588.
The functions work on PC or UNIX systems[1] with S-plus version 3.2 or later, but as the numerical calculations are quite large, we recommend a 586 (Pentium) or higher if it will be used on a PC.
The functions are implemented in S-plus code to make them easy to install on both PC
and UNIX systems. As the calculations can get very large this means that the routines may be time-consuming, but we hope to make the routines faster in later versions.
With 700 observations, the matrixes on some systems will become too large. To some degree, you can come around this problem by increaseing the S-plus option object.size as shown in the exsample below:
> options(object.size=1e+007)
Anyway, this takes quite a while, and we recommend data sets of just some hundred observations.
1. First download the package to your system either from a floppy disk or from "http://www.med.uio.no/imb/stat/addreg/download/addreg.tar.gz" at internet[2].
2. Go to your S-plus home directory:
~> cd `Splus SHOME `
~> cd library
Then make a directory for the functions:
~> mkdir addreg
~> cd addreg
Move the file with the package to this directory:
Example: ~> mv ~/addreg.tar.gz .
3. Now uncompress the package with:
~> gunzip addreg.tar.gz
And unpack the new file with:
~> tar -xf addreg.tar
You will now have the following files:
README.txt Short file descriptions addreg.eps Postscript documentation file addreg.html The same as addreg.eps but in hypertekst (without pictures etc.) addreg.q S-plus source file addreg.d Help files for the functions on NROFF input form make A make file for easier installation
5. Take a look at the documentation files, preferably with a postscript reader like Ghostview:
~> Ghostview addreg.eps &
6. After reading the documentation, the easiest way to install the routines is to use the "make" file. To do this you first must edit the make file for the S-plus home directory you use. For this you can use a text editor like "emacs":
~> emacs make &
After you specified the right S-plus directorie in the make file, just type:
~> make install
and you should then be up and running.
1. First download the package to your system either from a floppy disk or from "http://www.med.uio.no/imb/stat/addreg/download/addreg.zip" at internet[3].
2. The package you now got is packed with Phip Katz' program zip. If you have the program move the file to the catalogue "c:\addreg", and unpack it with using the file "c:\addreg\addreg.zip" in the zip program. Else se internet "http://www.target4.com/pkzip.hts" to get a copy of this shareware program.
You will now have the following files:
README.txt Short files descriptions addreg.doc Microsoft Word 6.0/7.0 documentation file addreg.html The same as addreg.doc but in hypertekst (without pictures etc.) addreg.q S-plus source file addreg.h Help file for the function addreg addreg.est.h Help file for the function addreg.est addreg.find.h Help file for the function addreg.find addreg.show.h Help file for the function addreg.show addreg.test.h Help file for the function addreg.test
3. Take a look at the documentation files, preferably with Microsoft Word or WordPerfect at the file "addreg.doc". If your system doesn't include any program that can read word files, you may use Netscape to view the hypertext version "addreg.html".
4. After reading the documentation, you start S-plus and then type:
> source("c:\\addreg\\addreg.q")
and the S-plus functions are installed.
5. To install the help function, just copy the helpfiles (all files with extension ".h") to your "_help" directory under your splus home directory[4]
Now you should be up and running.
The package comes with four different procedures:
addreg Finds and graphically displays the estimates addreg.est Shows estimates found by "addreg" addreg.find Computes the estimates and return them in matrix form addreg.show Displays graphically the estimates made by addreg.find addreg.test Finds the test values.For descriptions of the required attributes, side effects, ... se the help file, who comes as a attachments for this documentation.
As an example we will use data from page 255 of Kalbfleisch and Prentice[5].
Z1 = sex ( 1= male, 2 = female)
Z2 = treatment group (1 = standard, 2 = test)
Z3 = grade (1= well differentiated, 2 = moderately differentiated, 3 = poorly differentiated)
Z4 = age ( in years)
Z5 = condition (1=no disability, 2=restricted work, 3=requires assistance with self care 4=confined to bed)
Z6 = T-stage (an index of size and infiltration of tumour ranging from 1 to 4, with 1 indicating a small tumour and 4 a massive invasive tumour)
Z7 = N-stage (an index of lymph node metastasis ranging from 0 to 3, with 0 indicating no evidence of metastases and 3 indicating multiple positive nodes or fixed positive nodes).'.
1. How to get the data in the right format:
First we want the data in the following form:
Variable name
|
Data
of variable
|
| covar
|
Matrix
of covariate values.
Each observation is one row.
|
| times
|
Times
of death / censoring.
|
| censor
|
Indicates
death ( 1= death, 0 = censored).
|
> data <- matrix(scan("c:\\data\\data.txt"),byrow=T,ncol=9)
Where "ncol=9" means that the data have 9 variables for each[6] observation. Now the data is a s-plus matrix of the same size and format as the textfile matrix, and we can get the variables with:
> covar <- data[1:7,]
> times <- data[8,]
> censor <- data[9,]
The data are now in the right format.
2. How to find the estimates and get a graphical view of them:
This could be done with "addreg", but to reduce the time of compilation we store the estimates on the harddisk for further use. In this way we can se many different graphical views with just one calculation of the estimates.
We call the estimates "estres", and use the function "addreg.find" to find them:
> estres <- addreg.find(covar,times,cencor)
Remark: Stopped at time 1455 because of too low rank
"estres" are a tree dimensional array with estimates, and if we open a graphical devise[7], we can get a view of the estimates for the "condition" variable (which is variable number five) with:
> addreg.show(estres,5,"Condition")
Figure 4.1: Cumulative regression function for covariate "condition"
Or get a view of covariate 1 to 6, with:
> addreg.show(estres,c(1,2,3,4,5,6),label,"Survival of carcinome of the oropharynx",0,1200)
Figure 4.2 Splus view of regression functions for covariates 1 to 6 in
data "Survival of oropharynx".
Here variable number two is the column with the variables we want to view. Label is a column of labels for the variables. Then comes the title ("Survival of carcinome of the oropharynx") and where we want the estimation to start and finish. Except the estimates all other variables are optional, and we could just type:
> addreg.show(estres)
We then get a view of all variables (including the constant) over the full period of estimation, as show in the figure below:
Figure 4.3 All variables in data "Survival of oropharynx".
3. How to use the test routine.
It looks like covariate number five (condition) has a significant effect, and we can run a test on the variables with:
> addreg.test(orocovar,orotid,orostatus)
Remark: Resultes are taken at time 1446.284
Test-value: 10.1066 -1.6037 0.9337 -1.3913 0.271 4.113 2.5153 1.9861
P-value: 0 0.1088 0.3505 0.1641 0.7864 0 0.0119 0.047
[1] 0
This show that the covariate no. 5 is significant with any reasonable p-value etc.
Draw a cumulative additive regression estimate in survival analysis
DESCRIPTION:
This function calculates and plots, a cumulative additive regression estimate in survival analysis
USAGE:
addreg(covar, trisk, status, times, variablenr, labelofvariable, maintitle, startattime, stopattime)
REQUIRED ARGUMENTS:
covar
This variable contains the covariates of the analysis,
with one row for each subject
trisk
Observation times.
status
Status is 0 if the observation is censored, and 1 otherwise.
OPTIONAL ARGUMENTS:
variablenr
An array with the variables we want to include in the study. Default is all variables.
labelofvariable
Is an array with the text labels of the variables in the study. Default is just the number of the variables.
maintitle
A text for the main title.
startattime
The place where the drawing should start. Default is the first estimate.
stopattime
The place where the drawing should start. Default is the last estimate.
VALUE:
There is no value returned.
SIDE EFFECTS:
None
DETAILS:
1) The routine makes notes when the compilations stops.
2) A graphical Window must have been opened before starting this procedure.
REFERENCES:
Note on use is distributed with the package
("Documentation for S-plus package in additive survival analysis")
See also internet: http://med.uio.no/imb/stat/addreg/
Procedure written by: Harald Fekjaer, e-mail: hfe@math.uio.no
Theoretical work by: Prof. Odd O. Aalen
Research institute: Section of Medical Statistics, University of Oslo, Norway
Date: 1997
WARNING as needed:
THIS FUNCTION IS FREE AND COMES WITH ABSOLUTELY NO
WARRANTY, WHETHER FOR THE METHOD OR IT'S IMPLEMENTATION.
Finding the estimates can be very time consuming, so usually one does the estimation once and saves the results to the harddisk for further use. Se "addreg.find" and "addreg.show"
The routine that tests the rank of matrix is numeric, and can fail for very small values.
Please report to Harald Fekjaer (E-mail: hfe@math.uio.no) if you
find any weaknesses or have any ideas on how to improve the program.
SEE ALSO:
addreg.show , addreg.find, addreg.test, addreg.est
EXAMPLES:
We start the graphical window. In for example with UNIX:
> motif()
We take a look at the estimates with:
> addreg (covar, trisk, status)
Find a cumulative additive regression estimate in survival analysis
DESCRIPTION:
Function that finds an additive regression estimate in survival analysis,
and returns data with estimates, variances of estimates and the
relevant survival times.
USAGE:
addreg.find(covar, trisk, status,stoptime,stopcond,stand,na.rm)
REQUIRED ARGUMENTS:
covar
This variable contains the covariates of the analysis,
with one row for each subject
trisk
Observation times.
status
Status is 0 if the observation is censored, and 1 otherwise.
OPTIONAL ARGUMENTS:
stoptime
Here you can select the time for which you want the estimation
to stop. If you don't select any time the routine continues until
YY' becomes singular
stopcond
This is the test value for the rank of the matrix. Is's numeric and can fail for very small covariates. In this case one could adjust the variable "stoptime" to some lager number, but if you choose it to big, it will not let the estimates go so far in time as they could. Default value is 0.001
stand
If "stand" is true the covariat are standardised, that is, the mean is subtracted from each covarite . Default is true.
na.rm
If "na.rm" is true all observations with missing values are ignored. Default is true.
VALUE:
The function returns a three dimensional array with:
First element 1:
Is 1 for estimates of expectation and 2 for estimates of variances.
Second elements:
Number 1 is the times of estimates, then comes the constant,
covariate number 1, covariate number 2 ...
Last element:
Is the observation number
Remark: Normally the data are read by the function "addreg.show" or "addreg.est",
so that the user does not need to know anything about the data structure (see example).
SIDE EFFECTS:
None
DETAILS:
The routine makes notes when YY' becomes singular and the estimation stops.
REFERENCES:
Note on use is distributed with the package
("Documentation for S-plus package in additive survival analysis")
See also internet: http://med.uio.no/imb/stat/addreg/
Procedure written by: Harald Fekjaer, e-mail: hfe@math.uio.no
Theoretical work by: Prof. Odd O. Aalen
Research institute: Section of Medical Statistics, University of Oslo, Norway
Date: 1997
WARNING as needed:
THIS FUNCTION IS FREE AND COMES WITH ABSOLUTELY NO
WARRANTY, WHETHER FOR THE METHOD OR IT'S IMPLEMENTATION.
The routine that tests the rank of matrix is numeric, and can fail for very small covariate values. In this case one could adjust the variable "stoptime"
Please report to Harald Fekjaer (E-mail: hfe@math.uio.no) if you
find any weaknesses or have any ideas on how to improve the program.
SEE ALSO:
addreg.show , addreg.est , addreg.test, addreg
EXAMPLES:
To find and display results use:
> res <- addreg.find(covar, trisk, status)
> addreg.show(res)
Plots data on cumulative additive regression in survival analysis
DESCRIPTION:
Shows the cumulative additive regression estimates in survival analysis, calculated by the function addreg.find
USAGE:
addreg.show(linaerestimate, variablenr, labelofvariable, maintitle, startattime, stopattime)
REQUIRED ARGUMENTS:
linaerestimate
The data from the function addreg.find
OPTIONAL ARGUMENTS:
variablenr
An array with the variables we want to include in the study. Default is all variables.
labelofvariable
Is an array with the text labels of the variables in the study. Default is just the number of the variables.
maintitle
A text for the main title.
startattime
The place where the drawing should start. Default is the first estimate.
stopattime
The place where the drawing should start. Default is the last estimate.
VALUE:
There is no value returned.
SIDE EFFECTS:
None
DETAILS:
A graphical Window must have been opened before starting this procedure.
REFERENCES:
Note on use is distributed with the package
("Documentation for S-plus package in additive survival analysis")
See also internet: http://med.uio.no/imb/stat/addreg/
Procedure written by: Harald Fekjaer, e-mail: hfe@math.uio.no
Theoretical work by: Prof. Odd O. Aalen
Research institute: Section of Medical Statistics, University of Oslo, Norway
Date: 1997
WARNING as needed:
THIS FUNCTION IS FREE AND COMES WITH ABSOLUTELY NO
WARRANTY, WHETHER FOR THE METHOD OR IT'S IMPLEMENTATION.
Please report to Harald Fekjaer (E-mail: hfe@math.uio.no) if you
find any weaknesses or have any ideas on how to improve the program.
SEE ALSO:
addreg.find, addreg.test , addreg.est, addreg
EXAMPLES:
To find and display results use:
> res <- addreg.find(covar, trisk, status)
> addreg.show(res)
Finds the test values for additive regression estimates in survival analysis
DESCRIPTION:
Replace this line with brief description
USAGE:
addreg.test(covar, trisk, status, stopcond,stand,na.rm)
REQUIRED ARGUMENTS:
covar
This variable contains the covariates in the analysis,
with one row for each subject
trisk
Observation times.
status
Status is 0 if the observation is censored, and 1 otherwise.
OPTIONAL ARGUMENTS:
stopcond
This is the test value for the rank of the matrix. It is numeric and can fail for very small covariates. In this case one coud adjust the variable "stoptime" to some higher number, but if you choose it to soon, it will not lett the estimates go so far in time as they could. Default value is 0.001
stand
If "stand" is true the covariates are standardised, that is the mean is subtracted from each covariate. Default is true.
na.rm
If "na.rm" is true all observations with missing values are ignored. Default is true.
VALUE:
Returns an array of test statistics (with standard normal distribution under the assumptions that covariables are zero). First value is for the constant, and then comes each covariate. Under the test statistics the corresponding to sided p-values is printed.
SIDE EFFECTS:
None
DETAILS:
The routine makes notes when YY' becomes singular and the compilations stops.
REFERENCES:
Note on use is distributed with the package
("Documentation for S-plus package in additive survival analysis")
See also internet: http://med.uio.no/imb/stat/addreg/
Procedure written by: Harald Fekjaer, e-mail: hfe@math.uio.no
Theoretical work by: Prof. Odd O. Aalen
Research institute: Section of Medical Statistics, University of Oslo, Norway
Date: 1997
WARNING as needed:
THIS FUNCTION IS FREE AND COMES WITH ABSOLUTELY NO
WARRANTY, WHETHER FOR THE METHOD OR IT'S IMPLEMENTATION.
The routine that tests the rank of matrix is numeric, and can fail for very small covariate values. In this case one coud adjust the variable "stoptime"
Please report to Harald Fekjaer (E-mail: hfe@math.uio.no) if you
find any weaknesses or have any ideas on how to improve the program.
SEE ALSO:
addreg , addreg.show, addreg.find, addreg.est
EXAMPLES:
> addreg.test(orocovar,orotid,orostatus)
Remark: Resultes are taken at time 1446.284
Test-value: 10.1066 -1.6037 0.9337 -1.3913 0.271 4.113 2.5153 1.9861
P-value: 0 0.1088 0.3505 0.1641 0.7864 0 0.0119 0.047
[1] 0
Prints estimates for cumulative additive regression in survival analysis
DESCRIPTION:
Prints the cumulative additive regression estimates, calculated by the functions addreg.find
USAGE:
addreg.show(res , variablenr , times , digitsest , digitsvar)
REQUIRED ARGUMENTS:
linaerestimate
The data from the function addreg.find
variablenr
An array with the variables we want to include in the study. Default is all variables.
times
The times for which estimates should be printed.
OPTIONAL ARGUMENTS:
digitsest
Number of digits printed in estimate.
digitsvar
Number of digits printed in variance estimate.
VALUE:
There is no value returned.
SIDE EFFECTS:
None
DETAILS:
A graphical Window must have been opened before starting this procedure.
REFERENCES:
Note on use is distributed with the package
("Documentation for S-plus package in additive survival analysis")
See also internet: http://med.uio.no/imb/stat/addreg/
Procedure written by: Harald Fekjaer, e-mail: hfe@math.uio.no
Theoretical work by: Prof. Odd O. Aalen
Research institute: Section of Medical Statistics, University of Oslo, Norway
Date: 1997
WARNING as needed:
THIS FUNCTION IS FREE AND COMES WITH ABSOLUTELY NO
WARRANTY, WHETHER FOR THE METHOD OR IT'S IMPLEMENTATION.
Please report to Harald Fekjaer (E-mail: hfe@math.uio.no) if you
find any weaknesses or have any ideas on how to improve the program.
SEE ALSO:
addreg.find, addreg.test , addreg.est, addreg
EXAMPLES:
To find and display results use:
> res <- addreg.find(covar, trisk, status)
> addreg.est(res7,2,c(150,200))
Estimat for time 150 is:
Variable nr 2 : 0.06 with varianse 0.0001
Estimat for time 200 is:
Variable nr 2 : 0.06 with varianse 0.0001
[1] The functions are tested at IRIX (Silicon Graphics) and Sun Solaris systems.
[2] We recommend that you download the package over the net, as you the always gets the latest version.
[3] We recommend that you download the package over the net, as you the always gets the latest version.
[4] Often "c:\spluswin\data\_home"
[5] Kalbfleisch, J. D. and Prentice, R. L. The statistical Analysis of Failure Time Data, Wiley, New York, 1980.
[6] 7 covariates, one time variable and one censoring variable.
[7] In windows use "ALT-G" or "Tools -> Graphics Device -> Open -> Graphics ", and in UNIX use "mofif()" if you jusing x-windows.