Package 'AdhereR'

callAdhereR.

Description

The function encapsulating all the logics that allows AdhereR to be called from any platform using the generic shell mechanism.

Usage

callAdhereR(shared.data.directory)

Arguments

shared.data.directory

A string containing the path to the directory where all the exchanged (shared) data (both input and output) is. AdhereR needs read and write access to this directory.

Details

In most cases this should not be done directly by the user, but instead used by an appropriate wrapper on the client platform. It allows transparent use of AdhereR from virtually any platform or programming language for which an appropriate wrapper is provided. For more details see the vignette describing the included reference Python 3 wrapper.

Value

This function displays any messages to the console, tries to also write them to the Adherer-results.txt file in the shared.data.directory directory, and, when finished, forces R to quit with a given shell error code:

• 0 The processing ended without major errors;

• 1 General error (hopefully there are messages in the Adherer-results.txt file;

• 10 The directory shared.data.directory does not exit;

• 11 AdhereR does not have read access to the shared.data.directory directory;

• 12 AdhereR does not have write access to the shared.data.directory directory;

• 13 issues with the parameters file parameters.log;

• 14 issues with the data file dataset.csv;

• 15 plotting issues;

• 16 interactive plotting issues;

• 17 issues exporting the results.

---

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

See Also

CMA_sliding_window is very similar, computing a "simple" CMA for each of a set of same-size sliding windows. The "simple" CMAs that can be computed comprise CMA1, CMA2, CMA3, CMA4, CMA5, CMA6, CMA7, CMA8, CMA9, as well as user-defined classes derived from CMA0 that have a CMA component giving the estimated CMA per patient as a data.frame. If return.mapping.events.episodes is TRUE, then this also has a component mapping.episodes.to.events that gives the mapping between episodes and events as a data.table with the following columns:

• patid the patient ID.

• episode.ID the episode unique ID (increasing sequentially).

• event.index.in.data the event given by its row number in the data.

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)

---

CMA constructor for polypharmacy.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) object for polypharmacy.

Usage

CMA_polypharmacy(
  data = data,
  medication.groups = medication.class.colname,
  CMA.to.apply = NA,
  aggregate.first = TRUE,
  aggregation.method = NA,
  aggregation.method.arguments = NA,
  thresholds = NA,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  event.daily.dose.colname = NA,
  medication.class.colname = NA,
  carry.only.for.same.medication = NA,
  consider.dosage.change = NA,
  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",
  summary = "CMA for polypharmacy",
  force.NA.CMA.for.failed.patients = TRUE,
  parallel.backend = c("none", "multicore", "snow", "snow(SOCK)", "snow(MPI)",
    "snow(NWS)")[1],
  parallel.threads = "auto",
  suppress.warnings = FALSE,
  ...
)

Arguments

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, medication type, and might also contain the daily dosage (the actual column names are defined in the following four parameters).
medication.groups	A string with the name of the column containing the medication groups, or a *list of vectors* with medication class names (from medication.class.colname) belonging to the same treatment groupf multiple medication classes should belong to the same treatment group, they can be differentiated here (important to investigate treatment switches)
CMA.to.apply	A string giving the name of the CMA function (1 to 9) that will be computed for each treatment group.
aggregate.first	Logical, if TRUE, aggregate across treatment groups before summarizing over time during OW.
aggregation.method	A string giving the name of the function to aggregate CMA values of medication group, or NA to return only raw CMA estimates per medication group. Accepts summary functions such as "mean", "sd", "var", "min", "max", and "median". Custom functions are possible as long as they take a numeric vector as input and return a single numeric value.
aggregation.method.arguments	optional, A named list of additional arguments to the function given in aggregation method, e.g. na.rm = TRUE.
thresholds	optional, a number to apply as threshold between aggregation and summarizing.
ID.colname	A string, the name of the column in data containing the medication type. Defaults to medication.class.colname.
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.
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).
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; 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	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). Can be defined separately for each patient and treatment group.
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.
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.
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.
...	other possible parameters

Value

An S3 object of class CMA_polypharmacy 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).

• aggregation.method the aggregation method to combine CMA values from different groups.

• computed.CMA the class name of the computed CMA.

• medication.groups a data.frame with medication groups and classes

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column) and sometimes treatment group, with columns:

  • ID.colname the patient ID as given by the ID.colname parameter.

  • medication.groups only when no aggregation method is used (aggregation.method = NA); the treatment group as given by the medication.groups parameter.

  • CMA the treatment episode's estimated CMA.

Examples

## Not run: 
CMA_PP <- CMA_polypharmacy(data = med.events.pp,
medication.groups = med.groups,
CMA.to.apply = "CMA7",
aggregate.first = TRUE, # aggregate before summarizing
aggregation.method = "mean", # compute mean of CMAs
aggregation.method.arguments = list(na.rm = TRUE), # remove NA's during calculation
thresholds = NA, # don't apply threshold
ID.colname="PATIENT_ID",
event.date.colname="DATE",
event.duration.colname="DURATION",
event.daily.dose.colname="PERDAY",
medication.class.colname="CATEGORY",
followup.window.start=0,
observation.window.start=180,
observation.window.duration=365,
carry.only.for.same.medication = TRUE);
## End(Not run)

---

CMA_sliding_window constructor.

Description

Applies a given CMA to each sliding window and constructs a CMA_sliding_window object.

Usage

CMA_sliding_window(
  CMA.to.apply,
  data,
  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,
  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],
  sliding.window.start = 0,
  sliding.window.start.unit = c("days", "weeks", "months", "years")[1],
  sliding.window.duration = 90,
  sliding.window.duration.unit = c("days", "weeks", "months", "years")[1],
  sliding.window.step.duration = 30,
  sliding.window.step.unit = c("days", "weeks", "months", "years")[1],
  sliding.window.no.steps = NA,
  return.inner.event.info = FALSE,
  date.format = "%m/%d/%Y",
  summary = "CMA per sliding window",
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  return.mapping.events.sliding.window = 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,
  ...
)

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 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).
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.frames 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.
consider.dosage.change	Logical, if TRUE, the carry-over is adjusted to also reflect changes in dosage.
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).
sliding.window.start, sliding.window.start.unit, sliding.window.duration, sliding.window.duration.unit	the definition of the first sliding window (see the follow-up window parameters above for details).
sliding.window.step.duration, sliding.window.step.unit	if not missing (NA), these give the step (or "jump") to the right of the sliding window in time units.
sliding.window.no.steps	a integer specifying the desired number of sliding windows to cover the observation window (if possible); trumps sliding.window.step.duration and sliding.window.step.unit.
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.sliding.window	A Logical, if TRUE then the mapping between events and sliding windows is returned as the component mapping.windows.to.events, which is a data.table giving, for each sliding window, the events that belong to it (an event is given by its row number in the data).
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_sliding_window first computes a set of fixed-size (possibly partly overlapping) sliding windows, each sliding to the right by a fixed timelag, and then, for each of them, it computes the given "simple" CMA. 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_per_episode which computes a CMA for a set of treatment episodes.

Value

An S3 object of class CMA_sliding_window 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 sliding window, with columns:

  • ID.colname the patient ID as given by the ID.colname parameter.

  • window.ID the unique window ID (within patients).

  • window.start the window's start date (as a Date object).

  • window.end the window's end date (as a Date object).

  • CMA the window'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).

See Also

CMA_per_episode is very similar, computing a "simple" CMA for each of the treatment episodes. The "simple" CMAs that can be computed comprise CMA1, CMA2, CMA3, CMA4, CMA5, CMA6, CMA7, CMA8, CMA9, as well as user-defined classes derived from CMA0 that have a CMA component giving the estimated CMA per patient as a data.frame. If return.mapping.events.sliding.window is TRUE, then this also has an attribute mapping.windows.to.events that gives the mapping between episodes and events as a data.table with the following columns:

• patid the patient ID.

• window.ID the episode unique ID (increasing sequentially).

• event.index.in.data the event given by its row number in the data.

Examples

## Not run: 
cmaW <- CMA_sliding_window(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,
                           sliding.window.start=0,
                           sliding.window.start.unit="days",
                           sliding.window.duration=90,
                           sliding.window.duration.unit="days",
                           sliding.window.step.duration=7,
                           sliding.window.step.unit="days",
                           sliding.window.no.steps=NA,
                           date.format="%m/%d/%Y"
                          );
## End(Not run)

---

CMA0 constructor.

Description

Constructs a basic CMA (continuous multiple-interval measures of medication availability/gaps) object.

Usage

CMA0(
  data = 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",
  carryover.within.obs.window = NA,
  carryover.into.obs.window = NA,
  carry.only.for.same.medication = NA,
  consider.dosage.change = NA,
  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],
  date.format = "%m/%d/%Y",
  summary = "Base CMA object",
  suppress.warnings = FALSE,
  suppress.special.argument.checks = FALSE,
  arguments.that.should.not.be.defined = NULL,
  ...
)

Arguments

data	A data.frame containing the medication 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).
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.
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.frames 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.
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 medications 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 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).
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.
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.
arguments.that.should.not.be.defined	a list of argument names and pre-defined valuesfor which a warning should be thrown if passed to the function.
...	other possible parameters

Details

In most cases this should not be done directly by the user, but it is used internally by the other CMAs.

Value

An S3 object of class CMA0 with the following fields:

• data The actual event (prescribing or dispensing) 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.

• carryover.within.obs.window whether to consider the carry-over within the observation window, as given by the carryover.within.obs.window parameter.

• carryover.into.obs.window whether to consider the carry-over from before the starting date of the observation window, as given by the carryover.into.obs.window 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.

Examples

cma0 <- CMA0(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             event.daily.dose.colname="PERDAY",
             medication.class.colname="CATEGORY",
             followup.window.start=0,
             followup.window.start.unit="days",
             followup.window.duration=2*365,
             followup.window.duration.unit="days",
             observation.window.start=30,
             observation.window.start.unit="days",
             observation.window.duration=365,
             observation.window.duration.unit="days",
             date.format="%m/%d/%Y",
             summary="Base CMA");

---

CMA1 and CMA3 constructors.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 1 or type 3 object.

Usage

CMA1(
  data = NULL,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  medication.groups = NULL,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID",
  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],
  date.format = "%m/%d/%Y",
  summary = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  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.that.should.not.be.defined = c(carryover.within.obs.window = FALSE,
    carryover.into.obs.window = FALSE, carry.only.for.same.medication = FALSE,
    consider.dosage.change = FALSE),
  ...
)

CMA3(
  data = NULL,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  medication.groups = NULL,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID",
  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],
  date.format = "%m/%d/%Y",
  summary = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  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.that.should.not.be.defined = c(carryover.within.obs.window = FALSE,
    carryover.into.obs.window = FALSE, carry.only.for.same.medication = FALSE,
    consider.dosage.change = 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).
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.
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.frames 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.
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).
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.
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.
arguments.that.should.not.be.defined	a list of argument names and pre-defined valuesfor which a warning should be thrown if passed to the function.
...	other possible parameters

Details

CMA1 considers the total number of days with medication supplied in all medication events in the observation window, excluding the last event. CMA3 is identical to CMA1 except that it is capped at 100%.

The formula is

$(number of days supply excluding last) / (first to last event)$

Thus, the durations of all events are added up, possibly resulting in an CMA estimate (much) bigger than 1.0 (100%).

CMA2 and CMA1 differ in the inclusion or not of the last event.

Value

An S3 object of class CMA1 (derived from CMA0) 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.

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

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column).

Please note that if medication.groups are defined and flatten.medication.groups is FALSE, 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), but if flatten.medication.groups is FALSE then they are data.frames with an extra column giving the medication group (the column's name is given by medication.groups.colname).

See Also

CMAs 1 to 8 are described in:

Vollmer, W. M., Xu, M., Feldstein, A., Smith, D., Waterbury, A., & Rand, C. (2012). Comparison of pharmacy-based measures of medication adherence. BMC Health Services Research, 12, 155. doi:10.1186/1472-6963-12-155.

Examples

cma1 <- CMA1(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
cma3 <- CMA3(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );

---

CMA2 and CMA4 constructors.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 2 or type 4 object.

Usage

CMA2(
  data = NULL,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  medication.groups = NULL,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID",
  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],
  date.format = "%m/%d/%Y",
  summary = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  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.that.should.not.be.defined = c(carryover.within.obs.window = FALSE,
    carryover.into.obs.window = FALSE, carry.only.for.same.medication = FALSE,
    consider.dosage.change = FALSE),
  ...
)

CMA4(
  data = NULL,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  medication.groups = NULL,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID",
  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],
  date.format = "%m/%d/%Y",
  summary = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  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.that.should.not.be.defined = c(carryover.within.obs.window = FALSE,
    carryover.into.obs.window = FALSE, carry.only.for.same.medication = FALSE,
    consider.dosage.change = 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).
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.
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.frames 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.
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).
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.
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.
arguments.that.should.not.be.defined	a list of argument names and pre-defined valuesfor which a warning should be thrown if passed to the function.
...	other possible parameters

Details

CMA2 considers the total number of days with medication supplied in all medication events in the observation window, including the last event. CMA4 is identical to CMA2 except that it is capped at 100%.

The formula is

$(number of days supply including last event) / (first to last event)$

Thus, the durations of all events are added up, possibly resulting in an CMA estimate (much) bigger than 1.0 (100%)

CMA2 and CMA1 differ in the inclusion or not of the last event.

Value

An S3 object of class CMA2 (derived from CMA0) 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.

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

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column).

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

See Also

CMAs 1 to 8 are defined in:

Vollmer, W. M., Xu, M., Feldstein, A., Smith, D., Waterbury, A., & Rand, C. (2012). Comparison of pharmacy-based measures of medication adherence. BMC Health Services Research, 12, 155. doi:10.1186/1472-6963-12-155.

Examples

## Not run: 
cma2 <- CMA2(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
cma4 <- CMA4(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
## End(Not run)

---

CMA5 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 5 object.

Usage

CMA5(
  data = 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 = FALSE,
  consider.dosage.change = 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],
  date.format = "%m/%d/%Y",
  summary = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  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.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = FALSE),
  ...
)

Arguments

data	A data.frame containing the medication 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).
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.frames 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.
consider.dosage.change	Logical, if TRUE, the carry-over is adjusted to also reflect changes in dosage.
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).
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.
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.
arguments.that.should.not.be.defined	a list of argument names and pre-defined valuesfor which a warning should be thrown if passed to the function.
...	other possible parameters

Details

CMA5 assumes that, within the observation window, the medication is used as prescribed and new medication is "banked" until needed (oversupply from previous events is used first, followed new medication supply). It computes days of theoretical use by extracting the total number of gap days from the total time interval between the first and the last event, accounting for carry over for all medication events within the observation window. Thus, it accounts for timing within the observation window, and excludes the remaining supply at the start of the last event within the observation window.

The formula is

$(number of days of theoretical use) / (first to last event)$

Observations:

• the carry.only.for.same.medication parameter controls the transmission of carry-over across medication changes, producing a "standard" CMA5 (default value is FALSE), and an "alternative" CMA5b, respectively;

• the consider.dosage.change parameter controls if dosage changes are taken into account, i.e. if set as TRUE and a new medication event has a different daily dosage recommendation, carry-over is recomputed assuming medication use according to the new prescribed dosage (default value is FALSE).

Value

An S3 object of class CMA5 (derived from CMA0) 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).

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column).

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

See Also

CMAs 1 to 8 are defined in:

Vollmer, W. M., Xu, M., Feldstein, A., Smith, D., Waterbury, A., & Rand, C. (2012). Comparison of pharmacy-based measures of medication adherence. BMC Health Services Research, 12, 155. doi:10.1186/1472-6963-12-155.

Examples

cma5 <- CMA5(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=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );

---

CMA6 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 6 object.

Usage

CMA6(
  data = 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 = FALSE,
  consider.dosage.change = 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],
  date.format = "%m/%d/%Y",
  summary = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  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.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = 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).
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.frames 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.
consider.dosage.change	Logical, if TRUE, the carry-over is adjusted to also reflect changes in dosage.
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).
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.
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.
arguments.that.should.not.be.defined	a list of argument names and pre-defined valuesfor which a warning should be thrown if passed to the function.
...	other possible parameters

Details

CMA6 assumes that, within the observation window, the medication is used as prescribed and new medication is "banked" until needed (oversupply from previous events is used first, followed new medication supply). It computes days of theoretical use by extracting the total number of gap days from the total time interval between the first event and the end of the observation window, accounting for carry over for all medication events within the observation window. Thus, it accounts for timing within the observation window, and excludes the remaining supply at the end of the observation window.

The formula is

$(number of days of theoretical use) / (first event to end of observation window)$

Observations:

• the carry.only.for.same.medication parameter controls the transmission of carry-over across medication changes, producing a "standard" CMA6 (default value is FALSE), and an "alternative" CMA6b, respectively;

• the consider.dosage.change parameter controls if dosage changes are taken into account, i.e. if set as TRUE and a new medication event has a different daily dosage recommendation, carry-over is recomputed assuming medication use according to the new prescribed dosage (default value is FALSE).

Value

An S3 object of class CMA6 (derived from CMA0) 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).

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column).

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

See Also

CMAs 1 to 8 are defined in:

Vollmer, W. M., Xu, M., Feldstein, A., Smith, D., Waterbury, A., & Rand, C. (2012). Comparison of pharmacy-based measures of medication adherence. BMC Health Services Research, 12, 155. doi:10.1186/1472-6963-12-155.

Examples

cma6 <- CMA6(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=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );

---

CMA7 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 7 object.

Usage

CMA7(
  data = 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 = FALSE,
  consider.dosage.change = 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],
  date.format = "%m/%d/%Y",
  summary = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  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.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = TRUE),
  ...
)

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).
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.frames 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.
consider.dosage.change	Logical, if TRUE, the carry-over is adjusted to also reflect changes in dosage.
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).
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.
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.
arguments.that.should.not.be.defined	a list of argument names and pre-defined valuesfor which a warning should be thrown if passed to the function.
...	other possible parameters

Details

CMA7 assumes that, within and before the observation window, the medication is used as prescribed and new medication is "banked" until needed (oversupply from previous events is used first, followed new medication supply). It computes days of theoretical use by extracting the total number of gap days from the total time interval between the start and the end of the observation window, accounting for carry over for all medication events within and before the observation window. All medication events in the follow up window before observation window are considered for carry-over calculation. Thus, it accounts for timing within and before the observation window, and excludes the remaining supply at the end of the observation window.

The formula is

$(number of days of theoretical use) / (start to end of observation window)$

Observations:

• the carry.only.for.same.medication parameter controls the transmission of carry-over across medication changes, producing a "standard" CMA7 (default value is FALSE), and an "alternative" CMA7b, respectively;

• the consider.dosage.change parameter controls if dosage changes are taken into account, i.e. if set as TRUE and a new medication event has a different daily dosage recommendation, carry-over is recomputed assuming medication use according to the new prescribed dosage (default value is FALSE).

Value

An S3 object of class CMA7 (derived from CMA0) 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).

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column).

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

See Also

CMAs 1 to 8 are defined in:

Vollmer, W. M., Xu, M., Feldstein, A., Smith, D., Waterbury, A., & Rand, C. (2012). Comparison of pharmacy-based measures of medication adherence. BMC Health Services Research, 12, 155. doi:10.1186/1472-6963-12-155.

Examples

cma7 <- CMA7(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=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );

---

CMA8 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 8 object.

Usage

CMA8(
  data = 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 = FALSE,
  consider.dosage.change = 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],
  date.format = "%m/%d/%Y",
  summary = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  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.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = TRUE),
  ...
)

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).
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.frames 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.
consider.dosage.change	Logical, if TRUE, the carry-over is adjusted to also reflect changes in dosage.
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).
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.
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.
arguments.that.should.not.be.defined	a list of argument names and pre-defined valuesfor which a warning should be thrown if passed to the function.
...	other possible parameters

Details

CMA8 is similar to CMA6 in that it assumes that, within the observation window, the medication is used as prescribed and new medication is "banked" until needed (oversupply from previous events is used first, followed new medication supply). Unlike CMA6 it accounts for carry-over from before the window - but in a different way from CMA7: by adding a time lag at the start of the observation window equal to the duration of carry-over from before. It is designed for situations when an event with a hypothesized causal effect on adherence happens at the start of the observation window (e.g. enrolment in an intervention study); in this case, it may be that the existing supply is not part of the relationship under study (e.g. it delays the actual start of the study for that participant) and needs to be excluded by shortening the time interval examined. The end of the observation window remains the same. Thus, CMA8 computes days of theoretical use by extracting the total number of gap days from the total time interval between the lagged start and the end of the observation window, accounting for carry over for all medication events within the observation window. All medication events in the follow up window before observation window are considered for carry-over calculation. Thus, as CMA7, it accounts for timing within the observation window, as well as before (different adjustment than CMA7), and excludes the remaining supply at the end of the observation window.

The formula is

$(number of days of theoretical use) / (lagged start to end of observation window)$

Observations:

• the carry.only.for.same.medication parameter controls the transmission of carry-over across medication changes, producing a "standard" CMA8 (default value is FALSE), and an "alternative" CMA8b, respectively;

• the consider.dosage.change parameter controls if dosage changes are taken into account, i.e. if set as TRUE and a new medication event has a different daily dosage recommendation, carry-over is recomputed assuming medication use according to the new prescribed dosage (default value is FALSE).

Value

An S3 object of class CMA8 (derived from CMA0) 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).

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column).

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

See Also

CMAs 1 to 8 are defined in:

Vollmer, W. M., Xu, M., Feldstein, A., Smith, D., Waterbury, A., & Rand, C. (2012). Comparison of pharmacy-based measures of medication adherence. BMC Health Services Research, 12, 155. doi:10.1186/1472-6963-12-155.

Examples

cma8 <- CMA8(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=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );

---

CMA9 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 9 object.

Usage

CMA9(
  data = 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 = FALSE,
  consider.dosage.change = 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],
  date.format = "%m/%d/%Y",
  summary = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  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.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = TRUE),
  ...
)

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).
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.frames 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.
consider.dosage.change	Logical, if TRUE, the carry-over is adjusted to also reflect changes in dosage.
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).
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.
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.
arguments.that.should.not.be.defined	a list of argument names and pre-defined valuesfor which a warning should be thrown if passed to the function.
...	other possible parameters

Details

CMA9 is similar to CMA7 and CMA8 in that it accounts for carry-over within and before the observation window assuming that new medication is "banked" until needed (oversupply from previous events is used first, followed new medication supply). Yet, unlike these previous CMAs, it does not assume the medication is used as prescribed; in longitudinal studies with multiple CMA measures, this assumption may introduce additional variation in CMA estimates depending on when the observation window starts in relation to the previous medication event. A shorter time distance from the previous event (and longer to the first event in the observation window) results in higher values even if the number of gap days is the same, and it may also be that the patient has had a similar use pattern for that time interval, rather than perfect adherence followed by no medication use. CMA9 applies a different adjustment: it computes a ratio of days supply over each interval between two prescriptions and considers this applies for each day of that interval, up to 100% (moving oversupply to the next event interval). All medication events in the follow up window before observation window are considered for carry-over calculation. The last interval ends at the end of the follow-up window. Thus, it accounts for timing within the observation window, as well as before (but differently from CMA7 and CMA8), and excludes the remaining supply at the end of the observation window, if any.

The formula is

$(number of days in the observation window, each weighted by the ratio of days supply applicable to their event interval) / (start to end of observation window)$

Observations:

• the carry.only.for.same.medication parameter controls the transmission of carry-over across medication changes, producing a "standard" CMA7 (default value is FALSE), and an "alternative" CMA7b, respectively;

• the consider.dosage.change parameter controls if dosage changes are taken into account, i.e. if set as TRUE and a new medication event has a different daily dosage recommendation, carry-over is recomputed assuming medication use according to the new prescribed dosage (default value is FALSE).

Value

An S3 object of class CMA9 (derived from CMA0) 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).

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column).

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

cma9 <- CMA9(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=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );

---

Computation of event durations.

Description

Computes event durations based on dispensing, prescription, and other data (e.g. hospitalization data) and returns a data.frame which can be used with the CMA constructors in AdhereR.

Usage

compute_event_durations(
  disp.data = NULL,
  presc.data = NULL,
  special.periods.data = NULL,
  ID.colname,
  medication.class.colnames,
  disp.date.colname,
  total.dose.colname,
  presc.date.colname,
  presc.daily.dose.colname,
  presc.duration.colname,
  visit.colname,
  split.on.dosage.change = TRUE,
  force.init.presc = FALSE,
  force.presc.renew = FALSE,
  trt.interruption = c("continue", "discard", "carryover")[1],
  special.periods.method = trt.interruption,
  carryover = FALSE,
  date.format = "%d.%m.%Y",
  suppress.warnings = FALSE,
  return.data.table = FALSE,
  progress.bar = TRUE,
  ...
)

Arguments

disp.data	A data.frame or data.table containing the dispensing events. Must contain, at a minimum, the patient unique ID, one medication identifier, the dispensing date, and total dispensed dose, and might also contain additional columns to identify and group medications (the actual column names are defined in the medication.class.colnames parameter).
presc.data	A data.frame containing the prescribing events. Must contain, at a minimum, the same unique patient ID and medication identifier(s) as the dispensing data, the prescription date, the daily prescribed dose, and the prescription duration. Optionally, it might also contain a visit number.
special.periods.data	Optional, NULL or a data.frame containing the information about special periods (e.g., hospitalizations or other situations where medication use may differ, e.g. during incarcerations or holidays). Must contain the same unique patient ID as dispensing and prescription data, the start and end dates of the special periods with the exact column names DATE.IN and DATE.OUT. Optional columns are TYPE (indicating the type of special situation), customized instructions how to handle a specific period (see special.periods.method), and any of those specified in medication.class.colnames.
ID.colname	A string, the name of the column in disp.data, presc.data, and special.periods.data containing the unique patient ID.
medication.class.colnames	A Vector of strings, the name(s) of the column(s) in disp.data and presc.data containing the classes/types/groups of medication.
disp.date.colname	A string, the name of the column in disp.data containing the dispensing date (in the format given in the date.format parameter).
total.dose.colname	A string, the name of the column in disp.data containing the total dispensed dose as numeric (e.g. 500 for 10 tablets of 50 mg).
presc.date.colname	A string, the name of the column in presc.data containing the prescription date (in the format given in the date.format parameter).
presc.daily.dose.colname	A string, the name of the column in presc.data containing the daily prescribed dose as numeric (e.g. 50 for 50 mg once per day, or 25 for 50 mg once ever 2 days).
presc.duration.colname	A string, the name of the column in presc.data containing the duration of the prescription as numeric or NA if duration is unknown.
visit.colname	A string, the name of the column in presc.data containing the number of the visit or a new column name if the prescribing data does not contain such a column.
split.on.dosage.change	Logical or string. If TRUE split the dispensing event on days with dosage change and create a new event with the new dosage for the remaining supply. If string, the name of the column containing the Logical in disp.data for each medication class separatly. Important if carryover should be considered later on.
force.init.presc	Logical. If TRUE advance the date of the first prescription event to the date of the first dispensing event, if the first prescription event is after the first dispensing event for a specific medication. Only if the first prescription event is not limited in duration (as indicated in the presc.duration.colname).
force.presc.renew	Logical or string. If TRUE require a new prescription for all medications for every prescription event (visit), otherwise prescriptions end on the first visit without renewal. If string, the name of the column in disp.data containing the Logical for each medication class separatly.
trt.interruption	can be either of "continue", "discard", "carryover", or a string. It indicates how to handle durations during treatment interruptions (see special.periods.method). If string, the name of the (character) column in disp.data containing the information ("continue", "discard", or "carryover") for each medication class separatly.
special.periods.method	can be either of continue, discard, carryover, or custom. It indicates how to handle durations during special periods. With continue, special periods have no effect on durations and event start dates. With discard, durations are truncated at the beginning of special periods and the remaining quantity is discarded. With carryover, durations are truncated at the beginning of a special period and a new event with the remaining duration is created after the end of the end of the special period. With custom, the mapping has to be included in special.periods.data.
carryover	Logical, if TRUE apply carry-over to medications of the same type (according to medication.class.colnames). Can only be used together with CMA7 and above in combination with carry.only.for.same.medication = TRUE.
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).
suppress.warnings	Logical, if TRUE don't show any warnings.
return.data.table	Logical, if TRUE return a data.table object, otherwise a data.frame.
progress.bar	Logical, if TRUE show a progress bar.
...	other possible parameters.

Details

Computation of CMAs requires a supply duration for medications dispensed to patients. If medications are not supplied for fixed durations but as a quantity that may last for various durations based on the prescribed dose, the supply duration has to be calculated based on dispensed and prescribed doses. Treatments may be interrupted and resumed at later times, for which existing supplies may or may not be taken into account. Patients may be hospitalized or incarcerated, and may not use their own supplies during these periods. This function calculates supply durations, taking into account the aforementioned situations and providing various parameters for flexible adjustments.

Value

A list with the following elements:

• event_durations: A data.table or data.frame with the following columns:

  • ID.colname the unique patient ID, as given by the ID.colname parameter.

  • medication.class.colnames the column(s) with classes/types/groups of medication, as given by the medication.class.colnames parameter.

  • disp.date.colname the date of the dispensing event, as given by the disp.date.colnema parameter.

  • total.dose.colname the total dispensed dose, as given by the total.dose.colname parameter.

  • presc.daily.dose.colname the prescribed daily dose, as given by the presc.daily.dose.colname parameter.

  • DISP.START the start date of the dispensing event, either the same as in disp.date.colname or a later date in case of dosage changes or treatment interruptions/hospitalizations.

  • DURATION the calculated duration of the supply, based on the total dispensed dose and the prescribed daily dose, starting from the DISP.START date.

  • episode.start: the start date of the current prescription episode.

  • episode.end: the end date of the current prescription episode. Can be before the start date of the dispensing event if dispensed during a treatment interruption.

  • SPECIAL.DURATION the number of days during the current duration affected by special durations or treatment interruptions of type "continue".

  • CARRYOVER.DURATION the number of days after the current duration affected by special durations or treatment interruptions of type "carryover".

  • EVENT.ID: in case of multiple events with the same dispensing date (e.g. for dosage changes or interruptions); a unique ID starting at 1 for the first event

  • tot.presc.interruptions the total number of prescription interruptions per patient for a specific medication.

  • tot.dosage.changes the total number of dosage changes per patient for a specific medication.

• prescription_episodes: A data.table or data.frame with the following columns:

  • ID.colname: the unique patient ID, as given by the ID.colname parameter.

  • medication.class.colnames: the column(s) with classes/types/groups of medication, as given by the medication.class.colnames parameter.

  • presc.daily.dose.colname: the prescribed daily dose, as given by the presc.daily.dose.colname parameter.

  • episode.start: the start date of the prescription episode.

  • episode.duration: the duration of the prescription episode in days.

  • episode.end: the end date of the prescription episode.

• special_periods: A data.table or data.frame, the special.periods.data with an additional column SPECIAL.DURATION: the number of days between DATE.IN and DATE.OUT

• ID.colname the name of the columns containing the unique patient ID, as given by the ID.colname parameter.

• medication.class.colnames the name(s) of the column(s) in disp.data and presc.data containing the classes/types/groups of medication, as given by the medication.class.colnames parameter.

• disp.date.colname the name of the column in disp.data containing the dispensing date, as given in the disp.date.colname parameter.

• total.dose.colname the name of the column in disp.data containing the total dispensed dose, as given by the total.dose.colname parameter.

• presc.date.colname the name of the column in presc.data containing the prescription date, as given in the presc.date.colname parameter.

• presc.daily.dose.colname the name of the column in presc.data containing the daily prescribed dose, as given by the presc.daily.dose.colname parameter.

• presc.duration.colname the name of the column in presc.data containing the duration of the prescription, as given by the presc.duration.colname parameter.

• visit.colname the name of the column containing the number of the visit, as given by the visit.colname parameter

• split.on.dosage.change whether to split the dispensing event on days with dosage changes and create a new event with the new dosage for the remaining supply, as given by the split.on.dosage.change parameter.

• force.init.presc whether the date of the first prescription event was set back to the date of the first dispensing event, when the first prescription event was after the first dispensing event for a specific medication, as given by the force.init.presc parameter.

• force.presc.renew whether a new prescription was required for all medications for every prescription event (visit), as given by the force.presc.renew parameter.

• trt.interruption how durations during treatment interruptions were handled, as given by the trt.interruption parameter.

• special.periods.method as given by the special.periods.method parameter.

• date.format the format of the dates, as given by the date.format parameter.

Examples

## Not run: 
event_durations <- compute_event_durations(disp.data = durcomp.dispensing,
                                           presc.data = durcomp.prescribing,
                                           special.periods.data = durcomp.hospitalisation,
                                           ID.colname = "ID",
                                           presc.date.colname = "DATE.PRESC",
                                           disp.date.colname = "DATE.DISP",
                                           medication.class.colnames = c("ATC.CODE",
                                           "UNIT", "FORM"),
                                           total.dose.colname = "TOTAL.DOSE",
                                           presc.daily.dose.colname = "DAILY.DOSE",
                                           presc.duration.colname = "PRESC.DURATION",
                                           visit.colname = "VISIT",
                                           split.on.dosage.change = TRUE,
                                           force.init.presc = TRUE,
                                           force.presc.renew = TRUE,
                                           trt.interruption = "continue",
                                           special.periods.method = "continue",
                                           date.format = "%Y-%m-%d",
                                           suppress.warnings = FALSE,
                                           return.data.table = TRUE);
       
## End(Not run)

---