CMA9: CMA9 constructor.

In AdhereR: Adherence to Medications

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

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