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.
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,
...
)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).
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.
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.
A string, the name of the column in disp.data,
presc.data, and special.periods.data containing the unique patient ID.
A Vector of strings, the
name(s) of the column(s) in disp.data and presc.data containing
the classes/types/groups of medication.
A string, the name of the column in
disp.data containing the dispensing date (in the format given in
the date.format parameter).
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).
A string, the name of the column in
presc.data containing the prescription date (in the format given in
the date.format parameter).
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).
A string, the name of the column in
presc.data containing the duration of the prescription as numeric
or NA if duration is unknown.
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.
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.
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).
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.
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.
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.
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.
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).
Logical, if TRUE don't show any warnings.
Logical, if TRUE return a
data.table object, otherwise a data.frame.
Logical, if TRUE show a progress bar.
other possible parameters.
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.
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.
# 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);
# }
Run the code above in your browser using DataLab