compute_event_durations {AdhereR}R Documentation

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:

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)

[Package AdhereR version 0.7.0 Index]