Title: Weighted Cumulative Exposure Models
Version: 1.0.3
Depends: R (≥ 3.5.0)
Imports: plyr, survival, splines
Suggests: R.rsp
Description: A flexible method for modeling cumulative effects of time-varying exposures, weighted according to their relative proximity in time, and represented by time-dependent covariates. The current implementation estimates the weight function in the Cox proportional hazards model. The function that assigns weights to doses taken in the past is estimated using cubic regression splines.
License: GPL-2 | GPL-3
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.1
NeedsCompilation: no
Packaged: 2024-02-15 12:35:14 UTC; 15148
Author: Marie-Pierre Sylvestre ORCID iD [aut, cre], Marie-Eve Beauchamp [ctb], Ryan Patrick Kyle [ctb], Michal Abrahamowicz [ctb]
Maintainer: Marie-Pierre Sylvestre <marie-pierre.sylvestre@umontreal.ca>
Repository: CRAN
Date/Publication: 2024-02-15 13:20:05 UTC

WCE: Weighted Cumulative Exposure Models

Description

A flexible method for modeling cumulative effects of time-varying exposures, weighted according to their relative proximity in time, and represented by time-dependent covariates. The current implementation estimates the weight function in the Cox proportional hazards model. The function that assigns weights to doses taken in the past is estimated using cubic regression splines.

Author(s)

Maintainer: Marie-Pierre Sylvestre marie-pierre.sylvestre@umontreal.ca (ORCID)

Other contributors:

Obtain a hazard ratio (HR) from a WCE Cox proportional hazards model

Description

This function extracts the estimated coefficients from a WCE object.

Usage

HR.WCE(x, vecnum, vecdenom, allres = FALSE)

Arguments

x

A WCE object.

vecnum

A vector of time-dependent exposures corresponding to a scenario of interest (numerator of the HR).

vecdenom

A vector of time-dependent exposures corresponding to a scenario for the reference category (denominator of the HR).

allres

Logical. If FALSE, prints the results using the best model from the WCE object, i.e. among the models fitted with the different numbers of interior knots requested by nknots, based on AIC or BIC as specified in the WCE call. If TRUE, prints the results for all the estimated models available from the WCE object. Default to FALSE.

Details

Both vecnum and vecdenom need to be of the same length as the weight function cutof argument used in the call to WCE. The first value of each vector represents the exposure today (t1) and subsequent values represent the exposures in the past. The hazard ratio computed by HR.WCE corresponds to the ratio of the weighted cumulative exposures for the scenario of interest (vecnum) and the reference scenario (vecdenom). It corresponds to equation (8) of Sylvestre and Abrahamowicz (2009).

Value

Returns one or several hazard ratios. Inference may be obtained by bootstrap and has to be coded separately (please see WCE for an example).

References

Sylvestre, M. P., & Abrahamowicz, M. (2009). Flexible modeling of the cumulative effects of time-dependent exposures on the hazard. Statistics in medicine, 28(27), 3437-3453.

Examples

wce <- WCE(drugdata, "Cox", 1, 90, constrained = "R", id = "Id", event = "Event",
start = "Start", stop = "Stop", expos = "dose",covariates = c("age", "sex"))
# Exposed at a dose of 1 (constant) vs. unexposed over the time window of 90 days
scenario1 <- rep(1, 90)
scenario2 <- rep(0, 90)
HR.WCE(wce, vecnum = scenario1, vecdenom = scenario2)

Fit weighted cumulative exposure models

Description

WCE implements a flexible method for modeling cumulative effects of time-varying exposures, weighted according to their relative proximity in time, and represented by time-dependent covariates. The current implementation estimates the weight function in the Cox proportional hazards model. The function that assigns weights to doses taken in the past is estimated using cubic regression splines.

Usage

WCE(
  data,
  analysis = "Cox",
  nknots,
  cutoff,
  constrained = FALSE,
  aic = FALSE,
  MatchedSet = NULL,
  id,
  event,
  start,
  stop,
  expos,
  covariates = NULL,
  controls = NULL,
  ...
)

Arguments

data

A data frame in an interval (long) format, in which each line corresponds to one and only one time unit for a given individual.

analysis

Character string. One of 'Cox', 'NCC' or 'CC' for Cox proportional hazards model, conditional logistic regression for nested case controls ('NCC') or logistic regression for case-controls ('CC'). Currently only 'Cox' for the Cox proportional hazards model is implemented, calling the coxph function of the survival package.

nknots

A scalar or a vector. Corresponds to the number(s) of interior knots for the cubic splines to estimate the weight function. For example, if nknots is set to 2, then a model with two interior knots is fitted. If nknots is set to 1:3 or alternatively c(1,2,3) then three models with 1, 2, and 3 interior knots, respectively, are fitted.

cutoff

Integer. Time window over which the WCE model is estimated. Corresponds to the length of the estimated weight function.

constrained

Controls whether the weight function should be constrained to smoothly go to zero. Set to FALSE for unconstrained models, to 'Right' or 'R' to constrain the weight function to smoothly go to zero for exposure remote in time, and to 'Left' or 'L' to constrain the weight function to start a zero for the current values.

aic

Logical. If TRUE, then the AIC is used to select the best fitting model among those estimated for the different numbers of interior knots requested with nknots. If FALSE, then the BIC is used instead of the AIC. Default to FALSE (BIC). Note that the BIC implemented in WCE is the version suggested by Volinsky and Raftery in Biometrics (2000), which corresponds to BIC = 2 * log(PL) + p * log(d) where PL is the model's partial likelihood, p is the number of estimated parameters and d is the number of uncensored events. See Sylvestre and Abrahamowicz (2009) for more details.

MatchedSet

Argument required for 'NCC' analysis only. Corresponds to the variable in data that specifies the matched sets for the conditional logistic regression. Currently not implemented.

id

Name of the variable in data corresponding to the identification of subjects.

event

Name of the variable in data corresponding to event indicator. Must be coded 1 = event and 0 = no event.

start

Name of the variable in data corresponding to the starting time for the interval. Corresponds to time argument in function Surv in the survival package.

stop

Name of the variable in data corresponding to the ending time for the interval. Corresponds to time2 argument in function Surv in the survival package.

expos

Name of the variable in data corresponding to the exposure variable.

covariates

Optional. Vector of characters corresponding to the name(s) of the variable(s) in data corresponding to the covariate(s) to be included in the model. Default to NULL, which corresponds to fitting model(s) without covariates.

controls

List corresponding to the control parameters to be passed to the coxph function. See coxph.control for more details.

...

Optional; other parameters to be passed through to WCE.

Details

The current implementation of the WCE function does not allow missing values in the Id, event, start, stop, expos variables. Intervals in data determined by start and stop are assumed to be open on the left and closed on the right, (start, stop]. Intervals for a given individual (Id) must not overlap, and must cover the entire follow-up for the individual. The start and stop values for a given interval must not be equal. Delayed entry is not implemented in this version of the WCE function so all of the Id must start their follow-up at the same start value. The interior knots are placed at quantiles of the exposure variable distribution.

Value

A list of elements:

knotsmat List of vectors of knots used for the spline modelling of the weight function(s).
WCEmat Matrix of the estimated weight function. Each row corresponds to an estimated weight function. The number of columns in the WCEmat corresponds to the value of the argument nknots.
loglik Partial likelihood for each estimated model.
est List of vectors of estimated coefficients for the artificial time-dependent variables used to fit the WCE model(s).
vcovmat List of variance-covariance matrices estimated for each model.
SED List of vectors of estimated standard errors of the estimated coefficients of the artificial time-dependent variables used to fit each WCE model.
beta.hat.covariates List of vectors of estimated coefficients for the covariates.
se.covariates List of vectors of standard errors of the estimated coefficients for the covariates.
covariates Names of the covariates used in the estimation.
constrained Indicator of whether the model(s) was(were) unconstrained, right-constrained or left-constrained.
nevents Number of events.
aic Logical value corresponding to the aic argument.
info.criterion Value of the AIC or BIC for each model estimated.
analysis Value of the analysis argument.
... Optional, additional argument(s).

Note

Note that the print method for a WCE object returns the estimated WCE function(s), the number of events, the partial likelihoods, the AIC or BIC values, the matrix of coefficients estimates for the covariates (if any) and the matrix of standard error estimates for the covariates (if any).

References

Sylvestre, M. P., & Abrahamowicz, M. (2009). Flexible modeling of the cumulative effects of time-dependent exposures on the hazard. Statistics in medicine, 28(27), 3437-3453.

See Also

See also checkWCE, a function to check whether the arguments passed to WCE are correctly specified. See also summary, and plot for WCE objects.

Examples


wce <- WCE(drugdata, "Cox", 1, 90, constrained = "R", id = "Id", event = "Event",
start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"))
## Not run: 
 # Confidence intervals for HR, as well as pointwise confidence bands
 # for the estimated weight function can be obtained via bootstrap.

 # Set the number of bootstrap resamples
 #(set to 5 for demonstration purposes, should be higher)
 B <- 5

 # Obtain the list of ID for sampling
 ID <- unique(drugdata$Id)

 # Prepare vectors to extract estimated weight function and HR
 # for the best-fitting model for each bootstrap resample
 boot.WCE <- matrix(NA, ncol = 90, nrow=B)
 boot.HR <- rep(NA, B)

 # Sample IDs with replacement
 for (i in 1:B){
   ID.resamp <- sort(sample(ID, replace=T))
   datab <- drugdata[drugdata$Id %in% ID.resamp,] # select obs. but duplicated Id are ignored

   # deal with duplicated Id and assign them new Id
   step <- 1
   repeat {
   # select duplicated Id in ID.resamp
     ID.resamp <- ID.resamp[duplicated(ID.resamp)==TRUE]
     if (length(ID.resamp)==0) break # stop when no more duplicated Id to deal with
     # select obs. but remaining duplicated Id are ignored
     subset.dup <- drugdata[drugdata$Id %in% ID.resamp,]
     # assign new Id to duplicates
     subset.dup$Id <- subset.dup$Id + step * 10^ceiling(log10(max(drugdata$Id)))
     # 10^ceiling(log10(max(drugdata$Id)) is the power of 10
     # above the maximum Id from original data
     datab <- rbind(datab, subset.dup)
     step <- step+1
   }

   mod <- WCE(data = datab, analysis = "Cox", nknots = 1:3, cutoff = 90,
   constrained = "R", aic = FALSE, MatchedSet = NULL, id = "Id",
   event = "Event", start = "Start", stop = "Stop", expos = "dose",
   covariates = c("sex", "age"))

   # return best WCE estimates and corresponding HR
   best <- which.min(mod$info.criterion)
   boot.WCE[i,] <- mod$WCEmat[best,]
   boot.HR[i] <- HR.WCE(mod, rep(1, 90), rep(0, 90))
 }

 # Summarize bootstrap results using percentile method
 apply(boot.WCE, 2, quantile, p = c(0.05, 0.95))
 quantile(boot.HR, p = c(0.05, 0.95))

## End(Not run)

Verify that the arguments passed to the WCE function are in correct format

Description

This function checks whether the arguments passed to the WCE function are in the correct format. If at least one argument is incorrectly specified, the function returns an error message specifying what needs to be fixed.

Usage

checkWCE(data, id, event, start, stop, expos)

Arguments

data

A data frame in the long (interval) format with one line per unit of time.

id

The name of the variable in data that identifies subjects.

event

The name of the variable in data that identifies the events (must be 0 or 1).

start

The name of the variable in data that identifies the beginning of the interval.

stop

The name of the variable in data that identifies the end of the interval.

expos

The name of the variable in data that represents the exposure of interest.

Details

The arguments passed to checkWCE must be exactly those passed to WCE.

Value

checkWCE returns a message on the screen indicating whether the arguments are correctly specified or not.

Examples

checkWCE(drugdata, id = "Id", event = "Event",  start = "Start", stop = "Stop", expos = "dose")

Obtain estimated coefficients from WCE object

Description

This function extracts the estimated coefficients from a WCE object.

Usage

## S3 method for class 'WCE'
coef(object, ...)

Arguments

object

A WCE object.

...

Optional; other parameters to be passed through to coef.

Details

The function returns a list with one element if the WCE object was fitted without covariates and two if the WCE object was fitted with covariates. The first element is a matrix of estimated coefficients for the artificial D variables (see Sylvestre and Abrahamowicz, 2009). Each row of the matrix corresponds to a model with the number of knots specified in WCE. The second element of the list is a matrix of estimated covariate coefficients. Similarly, each row of the matrix corresponds to a model with the number of knots specified in WCE.

Value

WCEest Matrix of estimated coefficients of the artificial D variables.

covariates Matrix of estimated coefficients of the covariates (optional).

References

Sylvestre, M. P., & Abrahamowicz, M. (2009). Flexible modeling of the cumulative effects of time-dependent exposures on the hazard. Statistics in medicine, 28(27), 3437-3453.

See Also

WCE

Examples

wce <- WCE(data=drugdata, analysis="Cox", nknots=1, cutoff = 90, constrained = "R",
id = "Id", event = "Event", start = "Start", stop = "Stop", expos = "dose",
covariates = c("age", "sex"))
coef(wce)

Simulated dataset to illustrate the use of WCE models

Description

Simulated dataset to illustrate the use of WCE models

Usage

data(drugdata)

Format

A data frame with 77038 rows and 7 variables for 500 individuals. The data frame is formatted in an interval format.

Id

numeric vector to identify observations that belong to the same individual.

Event

numeric vector representing the event of interest. Takes the value of 1 in the interval during which the event occurs and is 0 otherwise.

Start

numeric vector indicating the beginning of the interval.

Stop

numeric vector indicating the end of the interval.

sex

numeric vector indicating males (0) and females (1).

age

numeric vector representing age at baseline.

dose

numeric vector representing time-dependent doses of a drug.

Details

The variables sex and age are covariates. They are optional and illustrate the inclusion of adjustment variables. Covariates can be numeric or factors.

Source

This dataset was simulated using the PermAlgo package (https://cran.r-project.org/package=PermAlgo).

References

Sylvestre, MP, & Abrahamowicz, M. (2008). Comparison of algorithms to generate event times conditional on time-dependent covariates. Statistics in Medicine, 27(14), 2618-2634.

Obtain the placement of the knots used for splines in WCE models

Description

This function extracts the knots placement for the spline function used to fit the WCE models.

Usage

knotsWCE(x)

Arguments

x

A WCE object.

Details

The function returns a list with one element if the WCE object was fitted without covariates and two if the WCE object was fitted with covariates. The first element is a matrix of estimated coefficients for the artificial D variables (see Sylvestre and Abrahamowicz, 2009). Each row of the matrix corresponds to a model with the number of knots specified in WCE. The second element of the list is a matrix of estimated covariate coefficients. Similarly, each row of the matrix corresponds to a model with the number of knots specified in WCE.

Value

Returns a list of vectors indicating the placement of the knots used in the spline function of each of the models fitted in the WCE object.

References

Sylvestre, M. P., & Abrahamowicz, M. (2009). Flexible modeling of the cumulative effects of time-dependent exposures on the hazard. Statistics in medicine, 28(27), 3437-3453.

Examples

wce <- WCE(drugdata, "Cox", 1, 90, constrained = "R", id = "Id", event = "Event",
start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"))
knotsWCE(wce)

Plot of the weight function(s) estimated by WCE

Description

Method to plot the weight function(s) of a WCE object. Can plot the best estimated weight function or all the estimated functions simultaneously.

Usage

## S3 method for class 'WCE'
plot(x, allres = FALSE, ...)

Arguments

x

A WCE object.

allres

Logical. If TRUE, then all the weight functions from the WCE object are plotted simultaneously. If FALSE, then only the best function, determined by AIC or BIC, is plotted. Default to FALSE.

...

Optional. Additional arguments to be passed to plot (none currently used).

References

Sylvestre, M. P., & Abrahamowicz, M. (2009). Flexible modeling of the cumulative effects of time-dependent exposures on the hazard. Statistics in medicine, 28(27), 3437-3453.

Examples

wce <- WCE(drugdata, "Cox", 1, 90, constrained = "R", id = "Id", event = "Event",
start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"))
plot(wce)

Summarize the results of a WCE object

Description

This is a method to summarize the results from either the best fitting or all of the estimated models from a WCE object.

Usage

## S3 method for class 'WCE'
summary(object, allres = FALSE, ...)

Arguments

object

A WCE object.

allres

Logical. If TRUE, then a summary is produced for every model from the WCE object. If FALSE, then a summary is produced only for the best fitting model, as determined by AIC or BIC. Default to FALSE.

...

Optional; other parameters to be passed through to summary.

Value

The summary method prints to screen the estimated coefficients, standard errors and p-values for the coefficients (if any) included in the WCE model. It also provides the partial likelihood and AIC or BIC value, and the number of events used in the estimation of the model.

References

Sylvestre, M. P., & Abrahamowicz, M. (2009). Flexible modeling of the cumulative effects of time-dependent exposures on the hazard. Statistics in medicine, 28(27), 3437-3453.

Examples

wce <- WCE(drugdata, "Cox", 1, 90, constrained = "R", id = "Id", event = "Event",
start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"))
summary(wce)

Obtain variance-covariance matrix from WCE models

Description

This function extracts the knots placement for the spline function used to fit the WCE models.

Usage

## S3 method for class 'WCE'
vcov(object, ...)

Arguments

object

A WCE object.

...

Optional; other parameters to be passed through to vcov.

Details

The function returns the variance-covariance matrix of the estimated regression coefficients from a WCE model.

Value

The function returns variance-covariance matrices with the estimated regression coefficients for the supplied WCE model object. The number of matrices returned is equivalent to the length of the nknots vector (or one matrix, if nknots is a scalar) passed to the WCE function when fitting the model.

References

Sylvestre, M. P., & Abrahamowicz, M. (2009). Flexible modeling of the cumulative effects of time-dependent exposures on the hazard. Statistics in medicine, 28(27), 3437-3453.

Examples

wce <- WCE(drugdata, "Cox", 1, 90, constrained = "R", id = "Id", event = "Event",
start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"))
vcov(wce)