AdhereR (version 0.4)

compute_event_durations: Computation of event durations.

Description

Computes event durations based on dispensing, prescription, and 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,
  hosp.data = NULL, ID.colname, presc.date.colname, disp.date.colname,
  date.format = "%d.%m.%Y", medication.class.colnames,
  total.dose.colname, presc.daily.dose.colname, presc.duration.colname,
  visit.colname, force.init.presc = FALSE, force.presc.renew = FALSE,
  split.on.dosage.change = TRUE, trt.interruption = c("continue",
  "discard", "carryover")[1], suppress.warnings = FALSE,
  return.data.table = FALSE, ...)

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.

hosp.data

Optional, NULL or a data.frame containing the hospitalization periods (or other situations where patients may not use their own supply, e.g. during incarcerations). Must contain the same unique patient ID as dispensing and prescription data, and the start and end dates of the hospitalizations with the exact column names DATE.IN and DATE.OUT.

ID.colname

A string, the name of the column in disp.data, presc.data, and hosp.data containing the unique patient ID.

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

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

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

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.

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

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 containing the Logical for each medication class separatly.

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 for each medication class separatly. Important if carryover should be considered later on.

trt.interruption

can be either continue, discard, or carryover, and indicates how to handle supplies affected by treatment interruptions or hospitalizations. With continue, interruptions have no effect on durations and dispensing start dates. With discard, supplies are truncated at the beginning of an interruption or hospitalization and the remaining supply is discarded. With carryover, supplies are truncated at the beginning of an interruption or hospitalization and a new dispensing start event with the remaining supply is created after the end of the interruption or hospitalization.

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.

...

other possible parameters.

Value

A data.frame or data.table 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.

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

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

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

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

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

• START.PRESC the start date of the prescription episode.

• END.PRESC the end date of the prescription episode.

• HOSP.DURATION the number of days during the current supply period affected by hospitalizations.

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

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.

Examples

# NOT RUN {
event_durations <- compute_event_durations(disp.data = durcomp.dispensing[1:3,],
                                           presc.data = durcomp.prescribing,
                                           hosp.data = durcomp.hospitalisation,
                                           ID.colname = "ID",
                                           presc.date.colname = "DATE.PRESC",
                                           disp.date.colname = "DATE.DISP",
                                           date.format = "%Y-%m-%d",
                                           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",
                                           force.init.presc = TRUE,
                                           force.presc.renew = TRUE,
                                           split.on.dosage.change = TRUE,
                                           trt.interruption = "continue",
                                           suppress.warnings = FALSE,
                                           return.data.table = TRUE);
# }