R: Computation of event durations.

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:

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.

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.8.1 Index]