compute.treatment.episodes: Compute Treatment Episodes.
In AdhereR: Adherence to Medications

compute.treatment.episodes

R Documentation

Compute Treatment Episodes.

Description

For a given event (prescribing or dispensing) database, compute the treatment episodes for each patient in various scenarious.

Usage

compute.treatment.episodes(
  data,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  event.daily.dose.colname = NA,
  medication.class.colname = NA,
  carryover.within.obs.window = TRUE,
  carry.only.for.same.medication = TRUE,
  consider.dosage.change = TRUE,
  medication.change.means.new.treatment.episode = TRUE,
  dosage.change.means.new.treatment.episode = FALSE,
  maximum.permissible.gap = 90,
  maximum.permissible.gap.unit = c("days", "weeks", "months", "years", "percent")[1],
  maximum.permissible.gap.append.to.episode = 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],
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  return.mapping.events.episodes = FALSE,
  date.format = "%m/%d/%Y",
  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, or `NA` if not defined.
`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), or `NA` if not defined.
`event.duration.colname`	A string, the name of the column in `data` containing the event duration (in days), or `NA` if not defined.
`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.
`carryover.within.obs.window`	Logical, if `TRUE` consider the carry-over within 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.
`medication.change.means.new.treatment.episode`	Logical, should a change in medication automatically start a new treatment episode?
`dosage.change.means.new.treatment.episode`	Logical, should a change in dosage automatically start a new treatment episode?
`maximum.permissible.gap`	The number of units given by `maximum.permissible.gap.unit` representing the maximum duration of permissible gaps between treatment episodes (can also be a percent, see `maximum.permissible.gap.unit` for details).
`maximum.permissible.gap.unit`	can be either "days", "weeks", "months", "years" or "percent", and represents the time units that `maximum.permissible.gap` refers to; if percent, then `maximum.permissible.gap` is interpreted as a percent (can be greater than 100%) of the duration of the current prescription.
`maximum.permissible.gap.append.to.episode`	a logical value specifying of the `maximum.permissible.gap` should be append at the end of an episode with a gap larger than the `maximum.permissible.gap`; `FALSE` (the default) mean no addition, while `TRUE` mean that the full `maximum.permissible.gap` is added.
`followup.window.start`	If a `Date` object it is 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; 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; or `NA` if not defined.
`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`	a number representing the duration of the follow-up window in the time units given in `followup.window.duration.unit`, or `NA` if not defined.
`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.
`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`.
`return.mapping.events.episodes`	A Logical, if `TRUE` then the mapping between events and episodes is returned as the attribute `mapping.episodes.to.events`, which is a `data.table` giving, for each episode, the events that belong to it (an event is given by its row number in the `data`). Please note that the episodes returned are quite "generic" (e.g., they include all the events in the FUW), because which events will be actually used in the computation of a `CMA_per_episode` depend on which simple CMA is used (see also `CMA_per_episode`), and should be used with care (we recommend using the mappings given by `CMA_per_episode` instead).
`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).
`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.

For the last treatment episode, the gap is considered only when longer than the maximum permissible gap. Please note the following:

episode starts at first medication event for a particular medication,
episode ends on the day when the last supply of that medication finished or if a period longer than the permissible gap preceded the next medication event, or at the end of the FUW,
end episode gap days represents either the number of days after the end of the treatment episode (if medication changed, or if a period longer than the permissible gap preceded the next medication event) or at the end of (and within) the episode, i.e. the number of days after the last supply finished (if no other medication event followed until the end of the FUW),
the duration of the episode is the interval between the episode start and episode end (and may include the gap days at the end, in the latter condition described above),
the number of gap days after the end of the episode can be computed as all values larger than the permissible gap and 0 otherwise,
if medication change starts new episode, then previous episode ends when the last supply is finished (irrespective of the length of gap compared to a maximum permissible gap); any days before the date of the new medication supply are considered a gap; this maintains consistency with gaps between episodes (whether they are constructed based on the maximum permissible gap rule or the medication change rule).

Value

A data.frame or data.table with the following columns (or NULL if no treatment episodes could be computed):

patid the patient ID.
episode.ID the episode unique ID (increasing sequentially).
episode.start the episode start date.
end.episode.gap.days the corresponding gap days of the last event in this episode.
episode.duration the episode duration in days.
episode.end the episode end date.

If mapping.episodes.to.events is TRUE, then this also has an attribute mapping.episodes.to.events that gives the mapping between episodes and events as a data.table with the following columns: