CMA_per_episode: CMA_per_episode constructor.
In AdhereR: Adherence to Medications

CMA_per_episode

R Documentation

CMA_per_episode constructor.

Description

Applies a given CMA to each treatment episode and constructs a CMA_per_episode object.

Usage

CMA_per_episode(
  CMA.to.apply,
  data,
  treat.epi = NULL,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  event.daily.dose.colname = NA,
  medication.class.colname = NA,
  medication.groups = NULL,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID",
  carry.only.for.same.medication = NA,
  consider.dosage.change = NA,
  medication.change.means.new.treatment.episode = TRUE,
  dosage.change.means.new.treatment.episode = FALSE,
  maximum.permissible.gap = 180,
  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.start.per.medication.group = FALSE,
  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],
  return.inner.event.info = FALSE,
  date.format = "%m/%d/%Y",
  summary = "CMA per treatment episode",
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  return.mapping.events.episodes = FALSE,
  parallel.backend = c("none", "multicore", "snow", "snow(SOCK)", "snow(MPI)",
    "snow(NWS)")[1],
  parallel.threads = "auto",
  suppress.warnings = FALSE,
  suppress.special.argument.checks = TRUE,
  ...
)

Arguments

`CMA.to.apply`	A string giving the name of the CMA function (1 to 9) that will be computed for each treatment episode.
`data`	A `data.frame` containing the events (prescribing or dispensing) 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).
`treat.epi`	A `data.frame` containing the treatment episodes. Must contain the patient ID (as given in `ID.colname`), the episode unique ID (increasing sequentially, `episode.ID`), the episode start date (`episode.start`), the episode duration in days (`episode.duration`), and the episode end date (`episode.end`).
`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 medication type, or `NA` if not defined.
`medication.groups`	A vector of characters defining medication groups or the name of a column in `data` that defines such groups. The names of the vector are the medication group unique names, while the content defines them as logical expressions. While the names can be any string of characters except "}", it is recommended to stick to the rules for defining vector names in `R`. For example, `c("A"="CATEGORY == 'medA'", "AA"="{A} & PERDAY < 4"` defines two medication groups: A which selects all events of type "medA", and B which selects all events already defined by "A" but with a daily dose lower than 4. If `NULL`, no medication groups are defined. If medication groups are defined, there is one CMA estimate for each group; moreover, there is a special group __ALL_OTHERS__ automatically defined containing all observations not covered by any of the explicitly defined groups.
`flatten.medication.groups`	Logical, if `FALSE` (the default) then the `CMA` and `event.info` components of the object are lists with one medication group per element; otherwise, they are `data.frame`s with an extra column containing the medication group (its name is given by `medication.groups.colname`).
`medication.groups.colname`	a string (defaults to ".MED_GROUP_ID") giving the name of the column storing the group name when `flatten.medication.groups` is `TRUE`.
`carry.only.for.same.medication`	Logical, if `TRUE`, the carry-over applies only across medication of the same type; valid only for CMAs 5 to 9, in which case it is coupled (i.e., the same value is used for computing the treatment episodes and the CMA on each treatment episode).
`consider.dosage.change`	Logical, if `TRUE`, the carry-over is adjusted to also reflect changes in dosage; valid only for CMAs 5 to 9, in which case it is coupled (i.e., the same value is used for computing the treatment episodes and the CMA on each treatment episode).
`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 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` or a string that conforms to the format specified in `date.format`); 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.start.per.medication.group`	a logical: if there are medication groups defined and this is `TRUE`, then the first event considered for the follow-up window start is relative to each medication group separately, otherwise (the default) it is relative to the patient.
`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).
`return.inner.event.info`	Logical specifying if the function should also return the event.info for all the individual events in each sliding window; by default it is `FALSE` as this information is useful only in very specific cases (e.g., plotting the event intervals) and adds a small but non-negligible computational overhead.
`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).
`summary`	Metadata as a string, briefly describing this CMA.
`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`.
`force.NA.CMA.for.failed.patients`	Logical describing how the patients for which the CMA estimation fails are treated: if `TRUE` they are returned with an `NA` CMA estimate, while for `FALSE` they are omitted.
`return.mapping.events.episodes`	A Logical, if `TRUE` then the mapping between events and episodes is returned as an extra component `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 specific to the particular simple CMA used, and should preferentially used over those returned by `compute.treatment.episodes()`. This component can also be accessed using the `getEventsToEpisodesMapping()` function.
`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.
`...`	other possible parameters

Details

CMA_per_episode first identifies the treatment episodes for the whole follo-up window (using the compute.treatment.episodes function), and then computes the given "simple" CMA for each treatment episode that intersects with the observation window. NB: the CMA is computed for the period of the episode that is part of the observations window; thus, if an episode starts earlier or ends later than the observation window, CMA will be computed for a section of that episode. Thus, as opposed to the "simple" CMAs 1 to 9, it returns a set of CMAs, with possibly more than one element.

It is highly similar to CMA_sliding_window which computes a CMA for a set of sliding windows.

Value

An S3 object of class CMA_per_episode with the following fields:

data The actual event data, as given by the data parameter.
ID.colname the name of the column in data containing the unique patient ID, as given by the ID.colname parameter.
event.date.colname the name of the column in data containing the start date of the event (in the format given in the date.format parameter), as given by the event.date.colname parameter.
event.duration.colname the name of the column in data containing the event duration (in days), as given by the event.duration.colname parameter.
event.daily.dose.colname the name of the column in data containing the prescribed daily dose, as given by the event.daily.dose.colname parameter.
medication.class.colname the name of the column in data containing the classes/types/groups of medication, as given by the medication.class.colname parameter.
carry.only.for.same.medication whether the carry-over applies only across medication of the same type, as given by the carry.only.for.same.medication parameter.
consider.dosage.change whether the carry-over is adjusted to reflect changes in dosage, as given by the consider.dosage.change parameter.
followup.window.start the beginning of the follow-up window, as given by the followup.window.start parameter.
followup.window.start.unit the time unit of the followup.window.start, as given by the followup.window.start.unit parameter.
followup.window.duration the duration of the follow-up window, as given by the followup.window.duration parameter.
followup.window.duration.unit the time unit of the followup.window.duration, as given by the followup.window.duration.unit parameter.
observation.window.start the beginning of the observation window, as given by the observation.window.start parameter.
observation.window.start.unit the time unit of the observation.window.start, as given by the observation.window.start.unit parameter.
observation.window.duration the duration of the observation window, as given by the observation.window.duration parameter.
observation.window.duration.unit the time unit of the observation.window.duration, as given by the observation.window.duration.unit parameter.
date.format the format of the dates, as given by the date.format parameter.
summary the metadata, as given by the summary parameter.
event.info the data.frame containing the event info (irrelevant for most users; see compute.event.int.gaps for details).
computed.CMA the class name of the computed CMA.
CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column) and treatment episode, with columns:
- ID.colname the patient ID as given by the ID.colname parameter.
- episode.ID the unique treatment episode ID (within patients).
- episode.start the treatment episode's start date (as a Date object).
- end.episode.gap.days the corresponding gap days of the last event in this episode.
- episode.duration the treatment episode's duration in days.
- episode.end the treatment episode's end date (as a Date object).
- CMA the treatment episode's estimated CMA.

Please note that if medication.groups are defined, then the CMA and event.info are named lists, each element containing the CMA and event.info corresponding to a single medication group (the element's name).

Examples

## Not run: 
cmaE <- CMA_per_episode(CMA="CMA1",
                        data=med.events,
                        ID.colname="PATIENT_ID",
                        event.date.colname="DATE",
                        event.duration.colname="DURATION",
                        event.daily.dose.colname="PERDAY",
                        medication.class.colname="CATEGORY",
                        carry.only.for.same.medication=FALSE,
                        consider.dosage.change=FALSE,
                        followup.window.start=0,
                        observation.window.start=0,
                        observation.window.duration=365,
                        date.format="%m/%d/%Y"
                       );
## End(Not run)

AdhereR documentation built on July 5, 2022, 5:08 p.m.