relsurv (version 2.0-9)

rs.surv: Compute a Relative Survival Curve

Description

Computes an estimate of the relative survival curve using the Ederer I, Ederer II method, Pohar-Perme method or the Hakulinen method

Usage

rs.surv(formula, data,ratetable=relsurv::slopop,na.action,fin.date,
            method="pohar-perme", conf.type="log",conf.int=0.95,type="kaplan-meier",
	    add.times,precision=1)

Arguments

formula

a formula object, with the response as a Surv object on the left of a ~ operator, and, if desired, terms separated by the + operator on the right. If the variables are not organized and named in the same way as in the population tables, a ratetable term must be added to match each subject to his/her expected cohort. For a single survival curve the ~ 1 part of the formula is not required.

NOTE: The time must be in days, and the same is required for the ratetable variables (the variables used in the population tables), for example age and year (year must be given in the date format, i.e. in number of days since 01.01.1960).

data

a data.frame in which to interpret the variables named in the formula.

ratetable

a table of event rates, organized as a ratetable object, such as slopop.

na.action

a missing-data filter function, applied to the model.frame, after any subset argument has been used. Default is options()$na.action.

fin.date

the date of the study ending, used for calculating the potential follow-up times in the Hakulinen method. If missing, it is calculated as max(year+time).

method

the method for calculating the relative survival. The options are pohar-perme(default), ederer1, ederer2 and hakulinen.

conf.type

one of plain, log (the default), or log-log. The first option causes the standard intervals curve +- k *se(curve), where k is determined from conf.int. The log option calculates intervals based on the cumulative hazard or log(survival). The last option bases intervals on the log hazard or log(-log(survival)).

conf.int

the level for a two-sided confidence interval on the survival curve(s). Default is 0.95.

type

defines how survival estimates are to be calculated given the hazards. The default (kaplan-meier) calculates the product integral, whereas the option fleming-harrington exponentiates the negative cumulative hazard. Analogous to the usage in survfit.

add.times

specific times at which the curve should be evaluated.

precision

Precision for numerical integration. Default is 1, which means that daily intervals are taken, the value may be decreased to get a higher precision or increased to achieve a faster calculation. The calculation intervals always include at least all times of event and censoring as border points.

Value

a survfit object; see the help on survfit.object for details. The survfit methods are used for print, summary, plot, lines, and points.

Details

NOTE: All times used in the formula argument must be specified in days. This is true for the follow-up time as well as for any variables needed ratetable object, like age and year.

The potential censoring times needed for the calculation of the expected survival by the Hakulinen method are calculated automatically. The times of censoring are left as they are, the times of events are replaced with fin.date - year.

The calculation of the Pohar-Perme estimate is more time consuming since more data are needed from the population tables. The old version of the function, now named rs.survo can be used as a faster version for the Hakulinen and Ederer II estimate.

Numerical integration is required for Pohar-Perme estimate. The integration precision is set with argument precision, which defaults to daily intervals, a default that should give enough precision for any practical purpose.

Note that even though the estimate is always calculated using numerical integration, only the values at event and censoring times are reported. Hence, the function plot draws a step function in between and the function summary reports the value at the last event or censoring time before the specified time. If the output of the estimated values at other points is required, this should be specified with argument add.times.

References

Package. Pohar M., Stare J. (2006) "Relative survival analysis in R." Computer Methods and Programs in Biomedicine, 81: 272--278

Relative survival: Pohar, M., Stare, J. (2007) "Making relative survival analysis relatively easy." Computers in biology and medicine, 37: 1741--1749.

See Also

survfit, survexp

Examples

# NOT RUN {
data(slopop)
data(rdata)
#calculate the relative survival curve
#note that the variable year is given in days since 01.01.1960 and that 
#age must be multiplied by 365.241 in order to be expressed in days.
rs.surv(Surv(time,cens)~sex+ratetable(age=age*365.241,sex=sex,
      year=year),ratetable=slopop,data=rdata)
# }