relsurv (version 2.2-3)

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,rmap)

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 no strata are used, ~1 should be specified.

NOTE: The follow-up time must be in days.

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.

rmap

an optional list to be used if the variables are not organized and named in the same way as in the ratetable object. See details below.

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: The follow-up time must be specified in days. The ratetable being used may have different variable names and formats than the user's data set, this is dealt with by the rmap argument. For example, if age is in years in the data set but in days in the ratetable object, age=age*365.241 should be used. The calendar year can be in any date format (date, Date and POSIXt are allowed), the date formats in the ratetable and in the data may differ.

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 Perme, M., Pavlic, K. (2018) "Nonparametric Relative Survival Analysis with the R Package relsurv". Journal of Statistical Software. 87(8), 1-27, doi: "10.18637/jss.v087.i08" Theory: Pohar Perme, M., Esteve, J., Rachet, B. (2016) "Analysing Population-Based Cancer Survival - Settling the Controversies." BMC Cancer, 16 (933), 1-8. doi:10.1186/s12885-016-2967-9. Theory: Pohar Perme, M., Stare, J., Esteve, J. (2012) "On Estimation in Relative Survival", Biometrics, 68(1), 113-120. doi:10.1111/j.1541-0420.2011.01640.x.

See Also

survfit, survexp

Examples

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