compute.event.int.gaps: Gap Days and Event (prescribing or dispensing) Intervals.
In AdhereR: Adherence to Medications

compute.event.int.gaps

R Documentation

Gap Days and Event (prescribing or dispensing) Intervals.

Description

For a given event (prescribing or dispensing) database, compute the gap days and event intervals in various scenarious.

Usage

compute.event.int.gaps(
  data,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  event.daily.dose.colname = NA,
  medication.class.colname = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  carryover.within.obs.window = FALSE,
  carryover.into.obs.window = FALSE,
  carry.only.for.same.medication = FALSE,
  consider.dosage.change = FALSE,
  followup.window.start = 0,
  followup.window.start.unit = c("days", "weeks", "months", "years")[1],
  followup.window.duration = 365 * 2,
  followup.window.duration.unit = c("days", "weeks", "months", "years")[1],
  observation.window.start = 0,
  observation.window.start.unit = c("days", "weeks", "months", "years")[1],
  observation.window.duration = 365 * 2,
  observation.window.duration.unit = c("days", "weeks", "months", "years")[1],
  date.format = "%m/%d/%Y",
  keep.window.start.end.dates = FALSE,
  remove.events.outside.followup.window = TRUE,
  keep.event.interval.for.all.events = FALSE,
  parallel.backend = c("none", "multicore", "snow", "snow(SOCK)", "snow(MPI)",
    "snow(NWS)")[1],
  parallel.threads = "auto",
  suppress.warnings = FALSE,
  suppress.special.argument.checks = FALSE,
  return.data.table = FALSE,
  ...
)

Arguments

`data`	A `data.frame` containing the events used to compute the CMA. Must contain, at a minimum, the patient unique ID, the event date and duration, and might also contain the daily dosage and medication type (the actual column names are defined in the following four parameters); the `CMA` constructors call this parameter `data`.
`ID.colname`	A string, the name of the column in `data` containing the unique patient ID; must be present.
`event.date.colname`	A string, the name of the column in `data` containing the start date of the event (in the format given in the `date.format` parameter); must be present.
`event.duration.colname`	A string, the name of the column in `data` containing the event duration (in days); must be present.
`event.daily.dose.colname`	A string, the name of the column in `data` containing the prescribed daily dose, or `NA` if not defined.
`medication.class.colname`	A string, the name of the column in `data` containing the classes/types/groups of medication, or `NA` if not defined.
`event.interval.colname`	A string, the name of a newly-created column storing the number of days between the start of the current event and the start of the next one; the default value "event.interval" should be changed only if there is a naming conflict with a pre-existing "event.interval" column in `event.info`.
`gap.days.colname`	A string, the name of a newly-created column storing the number of days when medication was not available (i.e., the "gap days"); the default value "gap.days" should be changed only if there is a naming conflict with a pre-existing "gap.days" column in `event.info`.
`carryover.within.obs.window`	Logical, if `TRUE` consider the carry-over within the observation window, or `NA` if not defined.
`carryover.into.obs.window`	Logical, if `TRUE` consider the carry-over from before the starting date of the observation window, or `NA` if not defined.
`carry.only.for.same.medication`	Logical, if `TRUE` the carry-over applies only across medication of the same type, or `NA` if not defined.
`consider.dosage.change`	Logical, if `TRUE` the carry-over is adjusted to reflect changes in dosage, or `NA` if not defined.
`followup.window.start`	If a `Date` object, it represents the actual start date of the follow-up window; if a string it is the name of the column in `data` containing the start date of the follow-up window either as the numbers of `followup.window.start.unit` units after the first event (the column must be of type `numeric`) or as actual dates (in which case the column must be of type `Date`); if a number it is the number of time units defined in the `followup.window.start.unit` parameter after the begin of the participant's first event.
`followup.window.start.unit`	can be either "days", "weeks", "months" or "years", and represents the time units that `followup.window.start` refers to (when a number), or `NA` if not defined.
`followup.window.duration`	either a number representing the duration of the follow-up window in the time units given in `followup.window.duration.unit`, or a string giving the column containing these numbers. Should represent a period for which relevant medication events are recorded accurately (e.g. not extend after end of relevant treatment, loss-to-follow-up or change to a health care provider not covered by the database).
`followup.window.duration.unit`	can be either "days", "weeks", "months" or "years", and represents the time units that `followup.window.duration` refers to, or `NA` if not defined.
`observation.window.start, observation.window.start.unit, observation.window.duration, observation.window.duration.unit`	the definition of the observation window (see the follow-up window parameters above for details).
`date.format`	A string giving the format of the dates used in the `data` and the other parameters; see the `format` parameters of the `as.Date` function for details (NB, this concerns only the dates given as strings and not as `Date` objects).
`keep.window.start.end.dates`	Logical, should the computed start and end dates of the windows be kept?
`remove.events.outside.followup.window`	Logical, should the events that fall outside the follo-wup window be removed from the results?
`keep.event.interval.for.all.events`	Logical, should the computed event intervals be kept for all events, or `NA`'ed for those outside the OW?
`parallel.backend`	Can be "none" (the default) for single-threaded execution, "multicore" (using `mclapply` in package `parallel`) for multicore processing (NB. not currently implemented on MS Windows and automatically falls back on "snow" on this platform), or "snow", "snow(SOCK)" (equivalent to "snow"), "snow(MPI)" or "snow(NWS)" specifying various types of SNOW clusters (can be on the local machine or more complex setups – please see the documentation of package `snow` for details; the last two require packages `Rmpi` and `nws`, respectively, not automatically installed with `AdhereR`).
`parallel.threads`	Can be "auto" (for `parallel.backend` == "multicore", defaults to the number of cores in the system as given by `options("cores")`, while for `parallel.backend` == "snow", defaults to 2), a strictly positive integer specifying the number of parallel threads, or a more complex specification of the SNOW cluster nodes for `parallel.backend` == "snow" (see the documentation of package `snow` for details).
`suppress.warnings`	Logical, if `TRUE` don't show any warnings.
`suppress.special.argument.checks`	Logical parameter for internal use; if `FALSE` (default) check if the important columns in the `data` have some of the reserved names, if `TRUE` this check is not performed.
`return.data.table`	Logical, if `TRUE` return a `data.table` object, otherwise a `data.frame`.
`...`	extra arguments.

Details

This should in general not be called directly by the user, but is provided as a basis for the extension to new CMAs.

Value

A data.frame or data.table extending the event.info parameter with:

event.interval Or any other name given in event.interval.colname, containing the number of days between the start of the current event and the start of the next one.
gap.days Or any other name given in gap.days.colname, containing the number of days when medication was not available for the current event (i.e., the "gap days").
.FU.START.DATE,.FU.END.DATE if kept, the actual start and end dates of the follow-up window (after adjustments due to the various parameters).
.OBS.START.DATE,.OBS.END.DATE if kept, the actual start and end dates of the observation window (after adjustments due to the various parameters).
.EVENT.STARTS.BEFORE.OBS.WINDOW if kept, TRUE if the current event starts before the start of the observation window.
.TDIFF1,.TDIFF2 if kept, various auxiliary time differences (in days).
.EVENT.STARTS.AFTER.OBS.WINDOW if kept, TRUE if the current event starts after the end of the observation window.
.CARRY.OVER.FROM.BEFORE if kept, the carry-over (if any) from the previous events.
.EVENT.WITHIN.FU.WINDOW if kept, TRUE if the current event is within the follow-up window.