Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 8 object.
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,
arguments.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
carryover.into.obs.window = TRUE),
...
)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).
A string, the name of the column in data
containing the unique patient ID; must be present.
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.
A string, the name of the column in
data containing the event duration (in days); must be present.
A string, the name of the column in
data containing the prescribed daily dose, or NA if not defined.
A string, the name of the column in
data containing the medication type, or NA if not defined.
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.
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).
a string (defaults to ".MED_GROUP_ID")
giving the name of the column storing the group name when
flatten.medication.groups is TRUE.
Logical, if TRUE, the
carry-over applies only across medication of the same type.
Logical, if TRUE, the carry-over
is adjusted to also reflect changes in dosage.
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.
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.
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.
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).
can be either "days",
"weeks", "months" or "years", and represents the time
units that followup.window.duration refers to, or NA if not
defined.
the definition of the observation window (see the follow-up window parameters above for details).
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).
Metadata as a string, briefly describing this CMA.
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.
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.
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.
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).
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).
Logical, if TRUE don't show any
warnings.
a list of argument names and pre-defined valuesfor which a warning should be thrown if passed to the function.
other possible parameters
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).
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).
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. 10.1186/1472-6963-12-155.
# NOT RUN {
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"
);
# }
Run the code above in your browser using DataLab