Package 'WCE' reference manual

Title:	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.
Authors:	Marie-Pierre Sylvestre [aut, cre] , Marie-Eve Beauchamp [ctb], Ryan Patrick Kyle [ctb], Michal Abrahamowicz [ctb]
Maintainer:	Marie-Pierre Sylvestre <[email protected]>
License:	GPL-2 \| GPL-3
Version:	1.0.3
Built:	2024-12-12 06:46:00 UTC
Source:	CRAN

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)
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")
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, ...)
## 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.

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)

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

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)

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)
knotsWCE(x)

Arguments

`x`	A `WCE` object.

Details

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)

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, ...)
## 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)

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, ...)
## 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)

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, ...)
## 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)

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

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

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)

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)

Package 'WCE'

Help Index

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

Description

Usage

Arguments

Details

Value

Examples

Obtain estimated coefficients from WCE object

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Simulated dataset to illustrate the use of WCE models

Description

Usage

Format

Details

Source

References

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

Description

Usage

Arguments

Details

Value

References

Examples

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

Description

Usage

Arguments

Details

Value

References

Examples

Plot of the weight function(s) estimated by WCE

Description

Usage

Arguments

References

Examples

Summarize the results of a WCE object

Description

Usage

Arguments

Value

References

Examples

Obtain variance-covariance matrix from WCE models

Description

Usage

Arguments

Details

Value

References

Examples

Fit weighted cumulative exposure models

Description

Usage

Arguments

Details

Value

Note

References

See Also

Examples

Obtain estimated coefficients from `WCE` object

Plot of the weight function(s) estimated by `WCE`