Joinpoint Model for Relative and Cause-Specific Survival

Description

This package is to analyze trends in survival with respect to year of diagnosis using joinpoint model.

Details

Survival data includes two temporal dimensions that are important to consider: the calendar year of diagnosis and the time since diagnosis. The JPSurv model is an extension of Cox proportional hazard model and of Hakulinen and Tenkanen in the case of relative survival, and fits a proportional hazard joinpoint model to survival data on the log hazard scale. Joinpoint models consist of linear segments connected through joinpoints. The probability (hazard) of cancer death is specified as the product of a baseline hazard (on time since diagnosis) and a multiplicative factor describing the effect of year of diagnosis and possibly other covariates. The effect of year of diagnosis is modeled as joined linear segments on the log scale. The number and location of joinpoints are estimated from data and represent the times at which trends changed. This model implies that the probability of cancer death as a function of time since diagnosis is proportional for individuals diagnosed in different calendar years. The software uses discrete-time survival data, i.e. survival data grouped by years since diagnosis in the life table format. The package accommodates both relative survival and cause-specific survival.

References

Yu B, Huang L, Tiwari RC, Feuer EJ, Johnson KA. Modelling population-based cancer survival trends by using join point models for grouped survival data. Journal of the Royal Statistical Society Series a-Statistics in Society. 2009;172:405-25.

Hakulinen T, Tenkanen L. Regression Analysis of Relative Survival Rates. Applied Statistics. 1987;36(3):309-17.

H. Wickham. ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York, 2009.

Figure - Percent Change in the Annual Probability of Dying of Cancer by Diagnosis Year

Description

A function that returns a plot (or a list including the Relative Change in Hazard trend measures and the plot) for percent change in the annual probability of dying of cancer by diagnosis year using ggplot. The annotation feature is available for nJP<=3 and the number of multiple intervals selected <=3.

Usage

Plot.dying.year.annotate(plotdata, fit, nJP, yearvar, 
                         obsintvar = "Relative_Survival_Interval", 
                         predintvar = "Predicted_ProbDeath_Int", 
                         interval = "Interval", 
                         annotation = 0, topanno = 1, trend = 0,
                         title = NULL)

Arguments

Value

The returned object is a list and depends on the values for trend and annotation. The list will contain some or all of the names plot_anno, plot_no_anno, and trends, where plot_anno is an object of class ggplot for a plot with annotations, plot_no_anno is an object of class ggplot for a plot without annotations, and trends is a list of data frames for the change in hazard trend measures with columns start.year, end.year, estimate, std.error, lowCI, upCI, and interval.

Author(s)

Fanni Zhang <zhangf@imsweb.com>

See Also

download.data, Plot.surv.year.annotate, Plot.surv.int.multiyears,aapc.

Examples

data("breast.example", package="JPSurv")
data("fit1", package="JPSurv")

yearvar<-"Year_of_diagnosis_1975"
obsintvar<-"Relative_Survival_Interval"
predintvar<-"Predicted_ProbDeath_Int"
interval<-"Interval"
nJP<-3
data.graph<-download.data(breast.example,fit1,nJP,yearvar,"graph",
                          subsetStr1,interval,int.select=c(1,3,5))
out.anno<-Plot.dying.year.annotate(data.graph,fit1,nJP,yearvar,obsintvar,
                     predintvar,interval,annotation=1,topanno=1,trend=1)
out<-Plot.dying.year.annotate(data.graph,fit1,nJP,yearvar,obsintvar,
                     predintvar,interval,annotation=0,topanno=0,trend=1)
trend.rch<-out.anno$trends
plot.rch.anno<-out.anno$plot_anno
plot.rch<-out$plot_no_anno

Figure - Cumulative Survival by Interval

Description

A function that returns a plot for Cumulative Survival by Interval supporting multiple selected years.

Usage

Plot.surv.int.multiyears(plotdata, fit, nJP, yearvar, 
                         obscumvar = "Relative_Survival_Cum", 
                         predcumvar = "Predicted_Survival_Cum", 
                         interval = "Interval", year.select = NULL)

Arguments

Value

An object of class ggplot containing the plot.

Author(s)

Fanni Zhang <zhangf@imsweb.com>

See Also

download.data,Plot.dying.year.annotate, Plot.surv.year.annotate.

Examples

data("breast.example", package="JPSurv")
data("fit3", package="JPSurv")

yearvar<-"Year_of_diagnosis_1975"
obscumvar<-"Relative_Survival_Cum"
predcumvar<-"Predicted_Survival_Cum"
interval<-"Interval"
nJP<-2
data.full<-download.data(breast.example,fit3,nJP,yearvar,"full",
                         subsetStr3,interval="Interval")
plot<-Plot.surv.int.multiyears(data.full,fit3,nJP,yearvar,obscumvar,
                    predcumvar,interval,year.select=c(1985,1990))

Figure - Average Change in Cumulative Survival by Diagnosis Year

Description

A function that returns a plot (or a list including the Absolute Change in Survival trend measures and the plot) for average change in cumulative survival by diagnosis year using ggplot. The annotation feature is available for nJP<=3 and the number of multiple intervals selected <=3.

Usage

Plot.surv.year.annotate(plotdata, fit, nJP, yearvar, 
                        obscumvar = "Relative_Survival_Cum", 
                        predcumvar = "Predicted_Survival_Cum", 
                        interval = "Interval", annotation = 0, 
                        trend = 0, title = NULL)

Arguments

Value

The returned object is a list and depends on the values for trend and annotation. The list will contain some or all of the names plot_anno, plot_no_anno, and trends, where plot_anno is an object of class ggplot for a plot with annotations, plot_no_anno is an object of class ggplot for a plot without annotations, and trends is a list of data frames for the change in hazard trend measures with columns start.year, end.year, estimate, std.error, lowCI, upCI, and interval.

Author(s)

Fanni Zhang <zhangf@imsweb.com>

See Also

download.data, Plot.dying.year.annotate, Plot.surv.int.multiyears,aapc.multiints.

Examples

data("breast.example", package="JPSurv")
data("fit3", package="JPSurv")

yearvar<-"Year_of_diagnosis_1975"
obscumvar<-"Relative_Survival_Cum"
predcumvar<-"Predicted_Survival_Cum"
interval<-"Interval"
nJP<-2
data.graph<-download.data(breast.example,fit3,nJP,yearvar,"graph",
                          subsetStr3,interval,int.select=c(1,5))

out<-Plot.surv.year.annotate(data.graph,fit3,nJP,yearvar,obscumvar,
                              predcumvar,interval,annotation=0,trend=0)

Trend summary measures for joinpoint relative survival model

Description

Get the trend summary measures for joinpoint relative survival model quickly using default interval=5 (if available). A function that returns the trend summary measures including the Absolute Change in Survival (ACS), the Relative Change in Survival (RCS) . and the Relative Change in Hazard (RCH) for each joinpoint segment

Usage

aapc(fit, type="AbsChgSur",interval=5)

Arguments

Value

A data frame with columns start.year, end.year, estimate, std.error, lowCI, upCI containing the estimates, standard errors, and confidence interval of the trend summary measure.

Examples

data("fit2", package="JPSurv")

# Get the estimate, standard error, and confidence interval of 
# the annual changes of cumulative relative survival for interval=5.
aapc(fit2, type="RelChgHaz")

Trend summary measures for multiple selected intervals

Description

A function that returns the trend summary measures including the Absolute Change in Survival (ACS), the Relative Change in Survival (RCS) and the Relative Change in Hazard (RCH) for each joinpoint segment given multiple selected intervals. It can also return the Weighted Average Abosulte Change in Survival for the user-specified ACS year range.

Usage

aapc.multiints(fit, type = "AbsChgSur", int.select = NULL, 
               ACS.range = NULL, ACS.out = NULL)

Arguments

Value

A list of data frames corresponding to each interval from int.select. Each data frame contains the columns start.year, end.year, estimate, std.error, lowCI, upCI for the estimates, standard errors, and confidence interval of the trend summary measure.

Author(s)

Fanni Zhang <zhangf@imsweb.com>

See Also

aapc

Examples

data("fit1", package="JPSurv")

aapc.multiints(fit1, type="RelChgHaz",int.select=c(1,3,5)) 

Data for examples

Description

Data frame containing breast cancer data used in examples.

Examples

 data("breast.example", package="JPSurv")

 # Display first two rows
 breast.example[1:2,]

SEERStat Dictionary Overview

Description

Reads the dictionary file and returns a parsed ovreview.

Usage

dictionary.overview(DICfilename)

Arguments

Value

A list which contains the parsed information stored in the dictionary file.

Combine inputs and outputs

Description

A function that returns a merged data set including the selected cohort input data and the accompanying data for plot.surv.year/plot.dying.year for the download feature in the JPSurv web app.

Usage

download.data(input, fit, nJP, yearvar, downloadtype, subset = NULL, 
              interval = "Interval", int.select = NULL)

Arguments

Value

A data frame containing the selected cohort input data and the below predicted columns.

Author(s)

Fanni Zhang <zhangf@imsweb.com>

References

The JPSurv web app https://analysistools.nci.nih.gov/jpsurv/.

See Also

Plot.dying.year.annotate, Plot.surv.year.annotate, Plot.surv.int.multiyears.

Examples

data("breast.example", package="JPSurv")
data("fit1", package="JPSurv")

nJP<-2                 
data.graph135<-download.data(breast.example,fit1,nJP,"Year_of_diagnosis_1975","graph",
                             subsetStr1,interval="Interval",int.select=c(1,3,5)) 
data.full<-download.data(breast.example,fit1,nJP,"Year_of_diagnosis_1975","full",subsetStr1)          

Fitted joinpoint object and subset string

Description

An object of class "joinpoint" used in examples.

Fitted joinpoint object and subset string

Description

An object of class "joinpoint" used in examples.

Fitted joinpoint object and subset string

Description

An object of class "joinpoint" used in examples.

Input data validation

Description

A function that validates the selected cohort data and returns an indicator along with a warning message if the selected cohort is not valid.

Usage

input.valid(input, subset = NULL)

Arguments

Value

If the cohort selection is available, value 1 will be returned; otherwise, value 0 will be returned and a warning message printed.

Fitting a join point relative survival model

Description

Fitting a joinpoint relative survival model

Usage

joinpoint(data, subset=NULL, na.action = na.fail, 
	year="Year", interval="Interval",
	number.event="Died", number.alive="Alive_at_Start", 
       number.loss="Lost_to_Followup",
	expected.rate="Expected_Survival_Interval", observedrelsurv = NULL,
	model.form = NULL, maxnum.jp = 0, proj.year.num=5,
	op=list(),
	delLastIntvl=FALSE, add.data.cols="_ALL_")

Arguments

Value

An object of class "joinpoint" will be returned with attributes:

References

Yu, B., Huang, L., Tiwari, R. C., Feuer, E. J. and Johnson, K. A. (2009), Modeling population-based cancer survival trends by using join point models for grouped survival data. Journal of the Royal Statistical Society: Series A, 172, 405-425.

Examples

#Load the provided SEER 18 breast cancer example data.
data("breast.example", package="JPSurv")

subsetStr="Year_of_diagnosis_1975 >= 1975 & Age_groups == '00-49' & Breast_stage == 'Localized'"
# Fit the survival join point model with zero join points, 
#  i.e., fit the proportional hazard relative survival model.
fit = joinpoint(data=breast.example,
                 subset = subsetStr,
                 year="Year_of_diagnosis_1975",
                 observedrelsurv="Relative_Survival_Cum",
                 model.form = NULL,
                 maxnum.jp = 0)

Choose cutpoint from joinpoint.relaxProp results

Description

Choose the cutpoint from the joinpoint.relaxProp returned object

Usage

joinpoint.choose.cutpoint(obj, cutpoint)

Arguments

Value

A list of class with the following objects:

References

Yu, B., Huang, L., Tiwari, R. C., Feuer, E. J. and Johnson, K. A. (2009), Modeling population-based cancer survival trends by using join point models for grouped survival data. Journal of the Royal Statistical Society: Series A, 172, 405-425.

See Also

joinpoint.relaxProp

Fitting a join point conditional relative survival model

Description

Fitting a joinpoint conditional relative survival model

Usage

joinpoint.cond(data, subset, start.interval, end.interval=NULL,
	year="Year", interval="Interval",
	number.event="Died", number.alive="Alive_at_Start", 
        number.loss="Lost_to_Followup",
	expected.rate="Expected_Survival_Interval",
	model.form=NULL, maxnum.jp=0, proj.year.num=5,
	op=list(), delLastIntvl=FALSE, add.data.cols="_ALL_")

Arguments

Details

The data to be included in the analysis must contain unique year, interval pairs. If not, then an error will be thrown. The subset option can be used to ensure that there are unique pairs of year and interval.

This function will set up the data based on the value of start by removing all rows with interval less than or equal to start and then call the joinpoint function.

Value

An object of class "joinpoint" will be returned with attributes:

References

Yu, B., Huang, L., Tiwari, R. C., Feuer, E. J. and Johnson, K. A. (2009), Modeling population-based cancer survival trends by using join point models for grouped survival data. Journal of the Royal Statistical Society: Series A, 172, 405-425.

See Also

joinpoint, joinpoint.conditional

Examples

#Load the provided SEER 18 breast cancer example data.
data("breast.example", package="JPSurv")
 
# Subset of observations to use
subset <- "Age_groups == '00-49' & Breast_stage == 'Localized'"

# Fit the conditional survival join point model with starting
#   interval 5 
fit <- joinpoint.cond(breast.example, subset, 5, 
                 year="Year_of_diagnosis_1975",
                 model.form=NULL, maxnum.jp=0)

Fitting a join point conditional relative survival model from the unconditional model

Description

Fitting a joinpoint conditional relative survival model from the unconditional model

Usage

joinpoint.conditional(fit.uncond, start.intervals, end.intervals, njp=NULL)

Arguments

Details

This function computes the conditional survival

P(T > t_{j+k} | T > t_{j}) = \frac{P(T > t_{j+k})}{P(T > t_{j})}, \hspace{0.1in} k = 1, \ldots , m

Value

A data frame similar to the fullpredicted data frame returned from joinpoint except that it will only the contain rows corresponding to the start.intervals and end.intervals that were specified. The data frame will also contain the additional column "Start.interval", and will be grouped by the start.intervals.

References

Yu, B., Huang, L., Tiwari, R. C., Feuer, E. J. and Johnson, K. A. (2009), Modeling population-based cancer survival trends by using join point models for grouped survival data. Journal of the Royal Statistical Society: Series A, 172, 405-425.

See Also

joinpoint, joinpoint.seerdata

Examples

#Load the provided SEER 18 breast cancer example data.
data("breast.example", package="JPSurv")
 
# Subset of observations to use
subset <- "Age_groups == '00-49' & Breast_stage == 'Localized'"

# Fit the unconditional survival join point model
fit <- joinpoint(breast.example, subset,
                 year="Year_of_diagnosis_1975",
                 model.form=NULL, maxnum.jp=0)

# Compute conditional survival S(10 | 5) = P(T>10 | T>5)
ret <- joinpoint.conditional(fit, 5, 10) 

Relaxing the proportionality assumption

Description

Fitting a joinpoint survival model by relaxing the proportionality assumption

Usage

joinpoint.relaxProp(data, subset, max.cutpoint=5,
       year="Year", interval="Interval", number.event="Died", 
       number.alive="Alive_at_Start", number.loss="Lost_to_Followup",
       expected.rate="Expected_Survival_Interval", 
       observed.rate="Observed_Survival_Interval", 
       model.form=NULL, maxnum.jp=0, 
       proj.year.num=5, op=list(), delLastIntvl=FALSE, add.data.cols=NULL)

Arguments

Details

This function finds the optimal clustering of intervals (1, ..., I), where I is the number of intervals, such that there are at most two ordered clusters of the form (1, ..., j) and (j+1, ..., I). For each ordered cluster, a model is fit and the BIC is computed. The algorithm is as follows:
1. Fit the (unconditional) joinpoint survival model on intervals (1, ..., I) and compute the BIC and call it BIC-0.
2. For each cutpoint j, j = 1, ..., max.cutpoint, fit the (unconditional) joinpoint survival model on intervals (1, ..., j) and fit the conditional joinpoint survival model on intervals (j+1, ..., I). Compute the BIC and label it BIC-j.
3. The optimal clustering is the one with minimum BIC = min(BIC-0, BIC-1, ...)

Value

A list of class "jp.relaxProp" with the following objects:

References

Yu, B., Huang, L., Tiwari, R. C., Feuer, E. J. and Johnson, K. A. (2009), Modeling population-based cancer survival trends by using join point models for grouped survival data. Journal of the Royal Statistical Society: Series A, 172, 405-425.

See Also

joinpoint, joinpoint.cond

Examples

#Load the provided SEER 18 breast cancer example data.
data("breast.example", package="JPSurv")
 
# Subset of observations to use
subset <- "Age_groups == '00-49' & Breast_stage == 'Localized'"
fit    <- joinpoint.relaxProp(breast.example, subset, max.cutpoint=2,
                              year="Year_of_diagnosis_1975")

Read in and format SEER*Stat data

Description

A function that reads in and format SEER*Stat data in a single step. Either numeric values or value labels can be imported.

Usage

joinpoint.seerdata(seerfilename,newvarnames,UseVarLabelsInData=FALSE)

Arguments

Value

A data frame containing the SEER*Stat data read in.

Examples

# For this example we will be referencing the SEER*Stat session that was used to 
# create the breast.example data included with the package.
# If the "breast.example.txt" is the output data file from SEER*Stat, then joinpoint.seerdata 
# can be used to input the data quickly, while taking into account the relevant information
# in the accompanying dictionary file.
# Input data is stored in breast.example
# breast.data = joinpoint.seerdata(seerfilename="breast.example", 
#                    newvarnames=c("Age_groups","Breast_Stage","Year_of_diagnosis_1975"),
#                    UseVarLabelsInData=FALSE)
# breast.data = joinpoint.seerdata(seerfilename="breast.example", 
#                    newvarnames=c("Breast_Stage","Year_of_diagnosis_1975"),
#                    UseVarLabelsInData=c("Breast_Stage","Year_of_diagnosis_1975"))
# The breast.data object can immediately be used as input to the joinpoint modeling function.

Plot of conditional survival versus year at diagnosis

Description

Plot of conditional survival versus year at diagnosis

Usage

jp.plot.cond.year(fit.cond, start.interval=NULL, end.interval=NULL,
                 year.col="Year", interval.col="Interval", 
                 relSurvInt.col="Relative_Survival_Interval", addToYear=0,
                 ylim=NULL)

Arguments

Details

The lines on the plot use the pred_cum column in fit.cond, while the points are from the relSurvInt.col column.

Value

NULL

See Also

joinpoint, joinpoint.conditional

Examples

#Load the provided SEER 18 breast cancer example data.
data("breast.example", package="JPSurv")
 
# Subset of observations to use
subset <- "Age_groups == '00-49' & Breast_stage == 'Localized'"

# Fit the unconditional survival join point model
fit <- joinpoint(breast.example, subset,
                 year="Year_of_diagnosis_1975",
                 model.form=NULL, maxnum.jp=0)

# Compute conditional survival S(10 | 5) = P(T>10 | T>5)
ret <- joinpoint.conditional(fit, 5, 10) 

jp.plot.cond.year(ret, year.col="Year_of_diagnosis_1975")

Plot of the annual probability of dying

Description

Plot of the annual probability of dying

Usage

jp.plot.death(fit.uncond, fit.cond, start.interval=NULL, end.interval=NULL,
                     year.col="Year", interval.col="Interval", 
                     relSurvInt.col="Relative_Survival_Interval", addToYear=0,
                     ylim=NULL)

Arguments

Details

The lines on the plot use the pred_int column in fit.cond, while the points are from the relSurvInt.col column.

Value

NULL

See Also

joinpoint, joinpoint.conditional

Examples

#Load the provided SEER 18 breast cancer example data.
data("breast.example", package="JPSurv")
 
# Subset of observations to use
subset <- "Age_groups == '00-49' & Breast_stage == 'Localized'"

# Fit the unconditional survival join point model
fit <- joinpoint(breast.example, subset,
                 year="Year_of_diagnosis_1975",
                 model.form=NULL, maxnum.jp=0)

# Compute conditional survival S(10 | 5) = P(T>10 | T>5)
ret <- joinpoint.conditional(fit, 5, 10) 

jp.plot.death(fit, ret, year.col="Year_of_diagnosis_1975")

Plot of conditional survival versus interval

Description

Plot of conditional survival versus interval

Usage

jp.plot.surv(fit.uncond, fit.cond, start.interval=NULL, end.interval=NULL,
                    year.col="Year", interval.col="Interval", 
                    relSurvInt.col="Relative_Survival_Interval", addToYear=0,
                    ylim=NULL, yearsToPlot=NULL, legend.pos="bottom")

Arguments

Details

The lines on the plot use the pred_cum column in fit.cond, while the points are from the relSurvInt.col column.

Value

NULL

See Also

joinpoint, joinpoint.conditional

Examples

#Load the provided SEER 18 breast cancer example data.
data("breast.example", package="JPSurv")
 
# Subset of observations to use
subset <- "Age_groups == '00-49' & Breast_stage == 'Localized'"

# Fit the unconditional survival join point model
fit <- joinpoint(breast.example, subset,
                 year="Year_of_diagnosis_1975",
                 model.form=NULL, maxnum.jp=0)

# Compute conditional survival S(10 | 5) = P(T>10 | T>5)
ret <- joinpoint.conditional(fit, 5, 10) 

jp.plot.surv(fit, ret, year.col="Year_of_diagnosis_1975")