Title: | Bivariate Alternating Recurrent Event Data Analysis |
---|---|
Description: | A collection of models for bivariate alternating recurrent event data analysis. Includes non-parametric and semi-parametric methods. |
Authors: | Sandra Castro-Pearson [aut, cre], Aparajita Sur [aut], Chi Hyun Lee [aut], Chiung-Yu Huang [aut], Xianghua Luo [aut] |
Maintainer: | Sandra Castro-Pearson <[email protected]> |
License: | GPL-3 |
Version: | 1.2.1 |
Built: | 2024-08-25 04:25:19 UTC |
Source: | https://github.com/sandracastropearson/bivrec |
Alternating recurrent event data arise frequently in biomedical and social sciences where two types of events such as hospital admissions and discharges occur alternatively over time.
As such we implement a collection of nonparametric and semiparametric methods to analyze this type of data.
The main functions are bivrecReg
and bivrecNP
. Use bivrecReg
for the estimation of covariate effects on the two alternating event gap times (xij and yij) using semiparametric methods. The method options are "Lee.et.al" and "Chang".
Use bivrecNP
for the estimation of the joint cumulative distribution function (cdf) for the two alternating events gap times (xij and yij) as well as the marginal survival function for the Type I gap times (xij) and the conditional cdf of the Type II gap times (yij) given an interval of the Type I gap times (xij) in a nonparametric fashion.
The package also provides options to simulate and visualize the data and the results of analysis.
Sandra Castro-Pearson, Aparajita Sur, Chi Hyun Lee, Chiung-Yu Huang, Xianghua Luo
Chang S-H. (2004). Estimating marginal effects in accelerated failure time models for serial sojourn times among repeated events. Lifetime Data Analysis, 10: 175-190. doi:10.1023/B:LIDA.0000030202.20842.c9
Huang CY, Wang MC. (2005). Nonparametric estimation of the bivariate recurrence time distribution. Biometrics, 61: 392-402. doi:10.1111/j.1541-0420.2005.00328.x
Lee CH, Huang CY, Xu G, Luo X. (2018). Semiparametric regression analysis for alternating recurrent event data. Statistics in Medicine, 37: 996-1008. doi:10.1002/sim.7563
Parzen MI, Wei LJ, Ying Z. (1994). A resampling method based on pivotal estimating functions. Biometrika, 81: 341-350. http://www.people.fas.harvard.edu/~mparzen/published/parzen1.pdf
Useful links:
Report bugs at https://github.com/SandraCastroPearson/BivRec/issues
Deprecated function from the previous version. Use bivrecReg
.
biv.rec.fit(formula, data, method, CI)
biv.rec.fit(formula, data, method, CI)
formula |
A formula with six variables indicating the bivariate alternating gap time response on the left of the ~ operator and the covariates on the right. The six variables on the left must have the same length and be given as
|
data |
A data frame that includes all the vectors/covariates listed in the formula above. |
method |
A string indicating which method to use to estimate effects of the covariates. See details. |
CI |
The level to be used for confidence intervals. Must be between 0.50 and 0.99. The default is 0.95. |
Two different estimation methods are available:
method = "Lee.et.al" (default) is a U-statistics-based smooth estimating function approach. See Lee, Huang, Xu, Luo (2018) for further details.
method = "Chang" is a rank-based estimating function approach. See Chang (2004) for further details. Note that following the Chang method, the variances of the estimated regression coefficients are approximated using the resampling techniques developed by Parzen, Wei and Ying (1994). This approximation requires extensive computing time for a relatively small sample size. In addition, using the Chang method does not guarantee convergence for the estimation of the coefficients.
See bivrecReg
Chang S-H. (2004). Estimating marginal effects in accelerated failure time models for serial sojourn times among repeated events. Lifetime Data Analysis, 10: 175-190. doi:10.1023/B:LIDA.0000030202.20842.c9
Lee CH, Huang CY, Xu G, Luo X. (2018). Semiparametric regression analysis for alternating recurrent event data. Statistics in Medicine, 37: 996-1008. doi:10.1002/sim.7563
Parzen MI, Wei LJ, Ying Z. (1994). A resampling method based on pivotal estimating functions. Biometrika, 81: 341-350. http://www.people.fas.harvard.edu/~mparzen/published/parzen1.pdf
Deprecated function from the previous version. Use bivrecNP
.
biv.rec.np(formula, data, CI, ai, u1, u2, conditional, given.interval)
biv.rec.np(formula, data, CI, ai, u1, u2, conditional, given.interval)
formula |
A formula with six variables indicating the bivariate alternating gap time response on the left of the ~ operator and the covariates on the right. The six variables on the left must have the same length and be given as
|
data |
A data frame that includes all the vectors listed in the formula. |
CI |
The level for confidence intervals the joint cdf, marginal survival and conditional cdf. Must be between 0.50 and 0.99. Default is 0.95. |
ai |
See details. |
u1 |
A vector or single number to be used for the estimation of joint cdf P(Type I gap times |
u2 |
A vector or single number to be used for the estimation of joint cdf P(Type I gap times |
conditional |
A logical value. If TRUE, this function will calculate the conditional cdf for the Type II gap time given an interval of the Type I gap time and the bootstrap standard error and confidence interval at the specified confidence level. Default is FALSE. |
given.interval |
A vector c(v1, v2) that must be specified if conditional = TRUE. The vector indicates an interval for the Type I gap time to use for the estimation of the cdf of the Type II gap time given this interval.
If given.interval = c(v1, v2), the function calculates P(Type II gap times |
ai
indicates a real non-negative function of censoring times to be used as weights in the nonparametric method. This variable can take on values of 1 or 2 which indicate:
ai=1
: the weights are simply 1 for all subjects, (default).
ai=2
: the weight for each subject is the subject's censoring time, .
See bivrecNP
.
Huang CY, Wang MC. (2005). Nonparametric estimation of the bivariate recurrence time distribution. Biometrics, 61: 392-402. doi:10.1111/j.1541-0420.2005.00328.x
Deprecated function from the previous version. Use plot.bivrecSurv
.
biv.rec.plot(formula, data)
biv.rec.plot(formula, data)
formula |
Formula of the form
|
data |
A data frame that contains all the vectors listed in the formula |
Deprecated function from the previous version. Use simBivRec
.
biv.rec.sim(nsize, beta1, beta2, tau_c, set)
biv.rec.sim(nsize, beta1, beta2, tau_c, set)
nsize |
Sample size which refers to the number of subjects in the data set where each subject could have multiple episodes of events. |
beta1 |
True coefficients for Type I gap times in the accelerated failure time model (AFT). |
beta2 |
True coefficients for Type II gap times in the accelerated failure time model (AFT). |
tau_c |
Maximum support of censoring time. It can take values as follows:
|
set |
Simulation setting based on scenarios outlined in Tables 1 and 2 in Lee, Huang, Xu, Luo (2018). Choose 1.1 (default) for scenario 1 with |
Data frame with the alternating recurrent event data and one continuous and one binary covariate.
Lee CH, Huang CY, Xu G, Luo X. (2018). Semiparametric regression analysis for alternating recurrent event data. Statistics in Medicine, 37: 996-1008. doi:10.1002/sim.7563
This function allows users to estimate the joint cumulative distribution function (cdf) for the two types of gap times (xij, yij), the marginal survival function for the Type I gap times (xij), and the conditional cdf for the Type II gap times (yij) given the Type I gap times (xij). See details for the estimation methods provided.
bivrecNP(response, ai, u1, u2, level, conditional, given.interval)
bivrecNP(response, ai, u1, u2, level, conditional, given.interval)
response |
A response object of class |
ai |
See details. |
u1 |
A vector or single number to be used for the estimation of joint cdf P(Type I gap times |
u2 |
A vector or single number to be used for the estimation of joint cdf P(Type I gap times |
level |
The confidence level for confidence intervals for joint cdf, marginal survival probability and conditional cdf. Must be between 0.50 and 0.99. Default is 0.95. |
conditional |
A logical value. If TRUE, this function will calculate the conditional cdf for the Type II gap time given an interval of the Type I gap time and the bootstrap standard error and confidence interval at the specified confidence level. Default is FALSE. |
given.interval |
A vector c(v1, v2) that must be specified if conditional = TRUE. The vector indicates an interval for the Type I gap time to use for the estimation of the cdf of the Type II gap time given this interval.
If given.interval = c(v1, v2), the function calculates P(Type II gap times |
ai
indicates a real non-negative function of censoring times to be used as weights in the nonparametric method. This variable can take on values of 1 or 2 which indicate:
ai=1
(default): the weights are simply 1 for all subjects, .
ai=2
: the weight for each subject is the subject's censoring time, .
Related methods: plot.bivrecNP
, head.bivrecNP
, print.bivrecNP
.
A bivrecNP object that contains:
joint_cdf
marginal_survival
conditional_cdf
(when conditional = TRUE)
formula
ai
level
given.interval
(when conditional = TRUE)
xij, yij
new_data
Huang CY, Wang MC. (2005). Nonparametric estimation of the bivariate recurrence time distribution. Biometrics, 61: 392-402. doi:10.1111/j.1541-0420.2005.00328.x
## Not run: library(BivRec) # Simulate bivariate alternating recurrent event data set.seed(28) sim_data <- simBivRec(nsize=100, beta1=c(0.5,0.5), beta2=c(0,-0.5), tau_c=63, set=1.1) bivrecsurv_data <- with(sim_data, bivrecSurv(id, epi, xij, yij, d1, d2)) npresult <- bivrecNP(response = bivrecsurv_data, ai=1, u1 = seq(2, 20, 2), u2 = seq(1, 14, 2), level=0.99) head(npresult) plot(npresult) #This is an example with longer runtime npresult2 <- bivrecNP(response = bivrecsurv_data, ai=1, u1 = seq(2, 20, 1), u2 = seq(1, 15, 1), conditional = TRUE, given.interval = c(0, 10), level = 0.99) head(npresult2) plot(npresult2) ## End(Not run)
## Not run: library(BivRec) # Simulate bivariate alternating recurrent event data set.seed(28) sim_data <- simBivRec(nsize=100, beta1=c(0.5,0.5), beta2=c(0,-0.5), tau_c=63, set=1.1) bivrecsurv_data <- with(sim_data, bivrecSurv(id, epi, xij, yij, d1, d2)) npresult <- bivrecNP(response = bivrecsurv_data, ai=1, u1 = seq(2, 20, 2), u2 = seq(1, 14, 2), level=0.99) head(npresult) plot(npresult) #This is an example with longer runtime npresult2 <- bivrecNP(response = bivrecsurv_data, ai=1, u1 = seq(2, 20, 1), u2 = seq(1, 15, 1), conditional = TRUE, given.interval = c(0, 10), level = 0.99) head(npresult2) plot(npresult2) ## End(Not run)
This function allows the user to evaluate covariate effects on two alternating recurrent events gap times (referred as Type I and Type II gap times) under the assumption that the two gap times follow accelerated failure time (AFT) models. See details for the estimation methods provided.
bivrecReg(formula, data, method)
bivrecReg(formula, data, method)
formula |
A formula with a |
data |
A data frame that includes the vectors needed for the |
method |
A string indicating which method to use to estimate effects of the covariates. See details. |
Two different estimation methods are available:
method = "Lee.et.al"
(default) is a U-statistics-based smooth estimating function approach. See Lee, Huang, Xu, Luo (2018) for further details.
method = "Chang"
is a rank-based estimating function approach. See Chang (2004) for further details.
Note that following the Chang method, the variances of the estimated regression coefficients are approximated using the resampling techniques developed by Parzen, Wei, Ying (1994).
This approximation requires extensive computing time for a relatively small sample size. In addition, using the Chang method does not guarantee convergence for the estimation of the coefficients and user may get the message, "Error: Max iterations reached. Did not converge.".
Related methods: coef.bivrecReg
, confint.bivrecReg
, plot
, print
, summary.bivrecReg
, vcov.bivrecReg
.
A bivrecReg object that contains:
call
lee_fit
or chang_fit
formula
data
Chang S-H. (2004). Estimating marginal effects in accelerated failure time models for serial sojourn times among repeated events. Lifetime Data Analysis, 10: 175-190. doi:10.1023/B:LIDA.0000030202.20842.c9
Lee CH, Huang CY, Xu G, Luo X. (2018). Semiparametric regression analysis for alternating recurrent event data. Statistics in Medicine, 37: 996-1008. doi:10.1002/sim.7563
Parzen MI, Wei LJ, Ying Z. (1994). A resampling method based on pivotal estimating functions. Biometrika, 81: 341-350. http://www.people.fas.harvard.edu/~mparzen/published/parzen1.pdf
## Not run: library(BivRec) set.seed(28) # Simulate bivariate alternating recurrent event data bivrec_data <- simBivRec(nsize=100, beta1=c(0.5,0.5), beta2=c(0,-0.5), tau_c=63, set=1.1) # Apply Lee, Huang, Xu, Luo (2018) method using two covariates lee_reg <- bivrecReg(bivrecSurv(id, epi, xij, yij, d1, d2) ~ a1 + a2, bivrec_data, "Lee.et.al") summary(lee_reg) ## End(Not run)
## Not run: library(BivRec) set.seed(28) # Simulate bivariate alternating recurrent event data bivrec_data <- simBivRec(nsize=100, beta1=c(0.5,0.5), beta2=c(0,-0.5), tau_c=63, set=1.1) # Apply Lee, Huang, Xu, Luo (2018) method using two covariates lee_reg <- bivrecReg(bivrecSurv(id, epi, xij, yij, d1, d2) ~ a1 + a2, bivrec_data, "Lee.et.al") summary(lee_reg) ## End(Not run)
This function creates a bivariate recurrent survival object to be used as a response variable in a model formula.
bivrecSurv(id, episode, xij, yij, d1, d2)
bivrecSurv(id, episode, xij, yij, d1, d2)
id |
Numeric or character vector of subject's unique identifier (i). |
episode |
Vector indicating the observation or episode (j) for a subject (i). This will determine order of events for each subject. |
xij |
Vector with the lengths of time spent in event of Type I for individual i in episode j. |
yij |
Vector with the lengths of time spent in event of Type II for individual i in episode j. |
d1 |
Vector of censoring indicator corresponding to Type I gap times (xij): = 1 for uncensored, and = 0 for censored gap times. |
d2 |
Vector of censoring indicator corresponding to Type II gap times (yij): = 1 for uncensored, and = 0 for censored gap times. Note that in the last episode (or pair) of gap times, yij is always censored, i.e., d2 = 0. |
All the following data requirements must be met to avoid errors or warnings:
All variables should have the same length.
The Type I (xij) and Type II (yij) gap times must be numeric and meet the requirements xij0, yij
0 respectively for all observations.
Only unique, positive, consecutive integers starting from 1, are allowed within each subject for episode (i.e., 1, 2, ...), but they should be allowed to be in any order in the raw data as long as they are unique and have no gap within each subject.
Censoring indicators d1 and d2 must be numeric. Only the last episode is allowed to have zero value for either, and for the last episode, the only combinations allowed are (d1, d2) = (0, 0) or (1, 0).
No missing values. If a subject has missing values in any variables, the whole subject's data will not be used.
A bivrecSurv object ready to be used as the response for analysis using bivrecReg
or bivrecNP
.
library(BivRec) set.seed(28) sim_data <- simBivRec(nsize=100, beta1=c(0.5,0.5), beta2=c(0,-0.5)) bivrecsurv_data <- with(sim_data, bivrecSurv(id, epi, xij, yij, d1, d2)) class(bivrecsurv_data)
library(BivRec) set.seed(28) sim_data <- simBivRec(nsize=100, beta1=c(0.5,0.5), beta2=c(0,-0.5)) bivrecsurv_data <- with(sim_data, bivrecSurv(id, epi, xij, yij, d1, d2)) class(bivrecsurv_data)
This function extracts the coefficients of a semiparametric regression fit.
## S3 method for class 'bivrecReg' coef(object, ...)
## S3 method for class 'bivrecReg' coef(object, ...)
object |
A |
... |
Additional parameters if needed. |
This function obtains the confidence interval for the coefficients of a semiparametric regression fit.
## S3 method for class 'bivrecReg' confint(object, parm, level, ...)
## S3 method for class 'bivrecReg' confint(object, parm, level, ...)
object |
A |
parm |
The parameters for which to run confidence interval. Default gets CI for all the covariates in the model. |
level |
Significance level. Default is 0.95. |
... |
Additional parameters if needed. |
This function prints the top elements of the joint cdf, marginal survival, and conditional cdf from a bivrecNP
object.
## S3 method for class 'bivrecNP' head(x, ...)
## S3 method for class 'bivrecNP' head(x, ...)
x |
A |
... |
additional parameters if needed |
This function plots all the estimated functions (joint cdf, marginal survival and conditional cdf if conditional=TRUE
during analysis) from a bivrecNP
object in one step.
## S3 method for class 'bivrecNP' plot(x, y = NULL, type = NULL, ...)
## S3 method for class 'bivrecNP' plot(x, y = NULL, type = NULL, ...)
x |
A |
y |
Either empty or NULL. |
type |
Optional vector of strings to label Type I and Type II gap times. Default is c("Type I", "Type II"). |
... |
Additional arguments to be passed to graphical methods if needed. |
This function plots bivariate recurrent event gap times from a bivrecSurv
object with an option to create separate plots based on categorical covariates.
## S3 method for class 'bivrecSurv' plot( x, y = NULL, by, type = NULL, main = NULL, xlab = NULL, ylab = NULL, col = NULL, ... )
## S3 method for class 'bivrecSurv' plot( x, y = NULL, by, type = NULL, main = NULL, xlab = NULL, ylab = NULL, col = NULL, ... )
x |
A |
y |
Either empty or NULL. |
by |
A vector or data frame with categorical variables. See details. |
type |
Optional vector of strings to label Type I and Type II gap times. Default is c("Type I", "Type II"). |
main |
Optional string with plot title. Default is no title (will go to default when using |
xlab |
Optional string with label for horizontal axis. Default is "Time". |
ylab |
Optional string with label for vertical axis. Default is "Individual". |
col |
Optional string vector with colors to use for each of the gap types. Default is c("red", "blue") |
... |
Additional arguments to be passed to graphical methods if needed. |
Argument by
must be a vector or data frame with one or several categorical variables (up to 6 categories each).
Plots of the bivariate alternating recurrent outcome will be created by category for each variable.
When the by
argument is used it overrides the main
argument and sets it to its default main=""
.
To avoid errors make sure the vectors used for the bivrecSurv
object have the same length as the categorical variables and no missing values.
## Not run: # Simulate bivariate alternating recurrent event data library(BivRec) set.seed(28) bivrec_data <- simBivRec(nsize=100, beta1=c(0.5,0.5), beta2=c(0,-0.5), tau_c=63, set=1.1) plot(x = with(bivrec_data,bivrecSurv(id, epi, xij, yij, d1, d2)), main="Example", type = c("In Hospital", "Out of Hospital")) #Present the data by subgroups #Note that the covariate a2 in the function will be dropped because it is continuous attach(bivrec_data) plot(x = bivrecSurv(id, epi, xij, yij, d1, d2), by = data.frame(a1, a2), type = c("In Hospital", "Out of Hospital")) detach(bivrec_data) ## End(Not run)
## Not run: # Simulate bivariate alternating recurrent event data library(BivRec) set.seed(28) bivrec_data <- simBivRec(nsize=100, beta1=c(0.5,0.5), beta2=c(0,-0.5), tau_c=63, set=1.1) plot(x = with(bivrec_data,bivrecSurv(id, epi, xij, yij, d1, d2)), main="Example", type = c("In Hospital", "Out of Hospital")) #Present the data by subgroups #Note that the covariate a2 in the function will be dropped because it is continuous attach(bivrec_data) plot(x = bivrecSurv(id, epi, xij, yij, d1, d2), by = data.frame(a1, a2), type = c("In Hospital", "Out of Hospital")) detach(bivrec_data) ## End(Not run)
This function plots the conditional cdf for a bivrecNP
object.
plotCond(object, type)
plotCond(object, type)
object |
An object of |
type |
Optional string to label the Type II gap time. Default is "Type II". |
This function plots the joint cdf for a bivrecNP
object.
plotJoint(object, type)
plotJoint(object, type)
object |
A |
type |
Optional vector of strings to label Type I and Type II gap times. Default is c("Type I", "Type II"). |
This function plots the marginal survival for a bivrecNP
object.
plotMarg(object, type)
plotMarg(object, type)
object |
An object of |
type |
Optional string to label the Type I gap time. Default is "Type I". |
This function prints a bivrecNP
object.
## S3 method for class 'bivrecNP' print(x, ...)
## S3 method for class 'bivrecNP' print(x, ...)
x |
An object of class |
... |
Additional parameters if needed. |
This function prints an object of class bivrecReg
.
## S3 method for class 'bivrecReg' print(x, ...)
## S3 method for class 'bivrecReg' print(x, ...)
x |
An object of class |
... |
Additional parameters if needed. |
This function prints a summary.bivrecReg
object.
## S3 method for class 'summary.bivrecReg' print(x, ...)
## S3 method for class 'summary.bivrecReg' print(x, ...)
x |
A |
... |
Additional parameters if needed. |
This function simulates a series of alternating recurrent events based on the simulation setting in Lee, Huang, Xu, Luo (2018).
simBivRec(nsize, beta1, beta2, tau_c, set)
simBivRec(nsize, beta1, beta2, tau_c, set)
nsize |
Sample size which refers to the number of subjects in the data set where each subject could have multiple episodes of events. |
beta1 |
True coefficients for Type I gap times in the accelerated failure time model (AFT). |
beta2 |
True coefficients for Type II gap times in the accelerated failure time model (AFT). |
tau_c |
Maximum support of censoring time. It can take values as follows:
|
set |
Simulation setting based on scenarios outlined in Tables 1 and 2 in Lee, Huang, Xu, Luo (2018). Choose 1.1 (default) for scenario 1 with |
Data frame with the alternating recurrent event data and one continuous and one binary covariate.
Lee CH, Huang CY, Xu G, Luo X. (2018). Semiparametric regression analysis for alternating recurrent event data. Statistics in Medicine, 37: 996-1008. doi:10.1002/sim.7563
library(BivRec) set.seed(1234) sim_data <- simBivRec(nsize=150, beta1=c(0.5,0.5), beta2=c(0,-0.5), tau_c=63, set=1.1) head(sim_data)
library(BivRec) set.seed(1234) sim_data <- simBivRec(nsize=150, beta1=c(0.5,0.5), beta2=c(0,-0.5), tau_c=63, set=1.1) head(sim_data)
This function provides a summary for the fit from semiparametric regression analysis.
## S3 method for class 'bivrecReg' summary(object, ...)
## S3 method for class 'bivrecReg' summary(object, ...)
object |
A |
... |
Additional parameters if needed. |
This function extracts the variance-covariance matrix from the fit of a semiparametric regression analysis.
## S3 method for class 'bivrecReg' vcov(object, ...)
## S3 method for class 'bivrecReg' vcov(object, ...)
object |
A |
... |
Additional parameters if needed. |