CMA0 constructor.

Description

Constructs a basic CMA (continuous multiple-interval measures of medication availability/gaps) object.

Usage

CMA0(
  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",
  carryover.within.obs.window = NA,
  carryover.into.obs.window = NA,
  carry.only.for.same.medication = NA,
  consider.dosage.change = NA,
  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 = "Base CMA object",
  suppress.warnings = FALSE,
  suppress.special.argument.checks = FALSE,
  arguments.that.should.not.be.defined = NULL,
  ...
)

Arguments

Details

In most cases this should not be done directly by the user, but it is used internally by the other CMAs.

Value

An S3 object of class CMA0 with the following fields:

• data The actual event (prescribing or dispensing) 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.

• carryover.within.obs.window whether to consider the carry-over within the observation window, as given by the carryover.within.obs.window parameter.

• carryover.into.obs.window whether to consider the carry-over from before the starting date of the observation window, as given by the carryover.into.obs.window 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.

Examples

cma0 <- CMA0(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             event.daily.dose.colname="PERDAY",
             medication.class.colname="CATEGORY",
             followup.window.start=0,
             followup.window.start.unit="days",
             followup.window.duration=2*365,
             followup.window.duration.unit="days",
             observation.window.start=30,
             observation.window.start.unit="days",
             observation.window.duration=365,
             observation.window.duration.unit="days",
             date.format="%m/%d/%Y",
             summary="Base CMA");

CMA1 and CMA3 constructors.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 1 or type 3 object.

Usage

CMA1(
  data = NULL,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  medication.groups = NULL,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID",
  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,
  suppress.special.argument.checks = TRUE,
  arguments.that.should.not.be.defined = c(carryover.within.obs.window = FALSE,
    carryover.into.obs.window = FALSE, carry.only.for.same.medication = FALSE,
    consider.dosage.change = FALSE),
  ...
)

CMA3(
  data = NULL,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  medication.groups = NULL,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID",
  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,
  suppress.special.argument.checks = TRUE,
  arguments.that.should.not.be.defined = c(carryover.within.obs.window = FALSE,
    carryover.into.obs.window = FALSE, carry.only.for.same.medication = FALSE,
    consider.dosage.change = FALSE),
  ...
)

Arguments

Details

CMA1 considers the total number of days with medication supplied in all medication events in the observation window, excluding the last event. CMA3 is identical to CMA1 except that it is capped at 100%.

The formula is

(number of days supply excluding last) / (first to last event)

Thus, the durations of all events are added up, possibly resulting in an CMA estimate (much) bigger than 1.0 (100%).

CMA2 and CMA1 differ in the inclusion or not of the last event.

Value

An S3 object of class CMA1 (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.

• 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 and flatten.medication.groups is FALSE, 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), but if flatten.medication.groups is FALSE then they are data.frames with an extra column giving the medication group (the column's name is given by medication.groups.colname).

See Also

CMAs 1 to 8 are described 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. doi: 10.1186/1472-6963-12-155.

Examples

cma1 <- CMA1(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
cma3 <- CMA3(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );

CMA2 and CMA4 constructors.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 2 or type 4 object.

Usage

CMA2(
  data = NULL,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  medication.groups = NULL,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID",
  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,
  suppress.special.argument.checks = TRUE,
  arguments.that.should.not.be.defined = c(carryover.within.obs.window = FALSE,
    carryover.into.obs.window = FALSE, carry.only.for.same.medication = FALSE,
    consider.dosage.change = FALSE),
  ...
)

CMA4(
  data = NULL,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  medication.groups = NULL,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID",
  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,
  suppress.special.argument.checks = TRUE,
  arguments.that.should.not.be.defined = c(carryover.within.obs.window = FALSE,
    carryover.into.obs.window = FALSE, carry.only.for.same.medication = FALSE,
    consider.dosage.change = FALSE),
  ...
)

Arguments

Details

CMA2 considers the total number of days with medication supplied in all medication events in the observation window, including the last event. CMA4 is identical to CMA2 except that it is capped at 100%.

The formula is

(number of days supply including last event) / (first to last event)

Thus, the durations of all events are added up, possibly resulting in an CMA estimate (much) bigger than 1.0 (100%)

CMA2 and CMA1 differ in the inclusion or not of the last event.

Value

An S3 object of class CMA2 (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.

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

See Also

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. doi: 10.1186/1472-6963-12-155.

Examples

## Not run: 
cma2 <- CMA2(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
cma4 <- CMA4(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
## End(Not run)

CMA5 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 5 object.

Usage

CMA5(
  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,
  suppress.special.argument.checks = TRUE,
  arguments.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = FALSE),
  ...
)

Arguments

Details

CMA5 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). It computes days of theoretical use by extracting the total number of gap days from the total time interval between the first and the last event, accounting for carry over for all medication events within the observation window. Thus, it accounts for timing within the observation window, and excludes the remaining supply at the start of the last event within the observation window.

The formula is

(number of days of theoretical use) / (first to last event)

Observations:

• the carry.only.for.same.medication parameter controls the transmission of carry-over across medication changes, producing a "standard" CMA5 (default value is FALSE), and an "alternative" CMA5b, 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).

Value

An S3 object of class CMA5 (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).

See Also

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. doi: 10.1186/1472-6963-12-155.

Examples

cma5 <- CMA5(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"
            );

CMA6 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 6 object.

Usage

CMA6(
  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,
  suppress.special.argument.checks = TRUE,
  arguments.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = FALSE),
  ...
)

Arguments

Details

CMA6 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). It computes days of theoretical use by extracting the total number of gap days from the total time interval between the first event and the end of the observation window, accounting for carry over for all medication events within the observation window. Thus, it accounts for timing within the observation window, and excludes the remaining supply at the end of the observation window.

The formula is

(number of days of theoretical use) / (first event 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" CMA6 (default value is FALSE), and an "alternative" CMA6b, 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).

Value

An S3 object of class CMA6 (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).

See Also

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. doi: 10.1186/1472-6963-12-155.

Examples

cma6 <- CMA6(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"
            );

CMA7 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 7 object.

Usage

CMA7(
  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,
  suppress.special.argument.checks = TRUE,
  arguments.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = TRUE),
  ...
)

Arguments

Details

CMA7 assumes that, within and before 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). It computes days of theoretical use by extracting the total number of gap days from the total time interval between the start and the end of the observation window, accounting for carry over for all medication events within and before the observation window. All medication events in the follow up window before observation window are considered for carry-over calculation. Thus, it accounts for timing within and before the observation window, and excludes the remaining supply at the end of the observation window.

The formula is

(number of days of theoretical use) / (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" CMA7 (default value is FALSE), and an "alternative" CMA7b, 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).

Value

An S3 object of class CMA7 (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).

See Also

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. doi: 10.1186/1472-6963-12-155.

Examples

cma7 <- CMA7(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"
            );

CMA8 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 8 object.

Usage

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,
  suppress.special.argument.checks = TRUE,
  arguments.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = TRUE),
  ...
)

Arguments

Details

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

Value

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

See Also

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. doi: 10.1186/1472-6963-12-155.

Examples

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"
            );

CMA9 constructor.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) type 9 object.

Usage

CMA9(
  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,
  suppress.special.argument.checks = TRUE,
  arguments.that.should.not.be.defined = c(carryover.within.obs.window = TRUE,
    carryover.into.obs.window = TRUE),
  ...
)

Arguments

Details

CMA9 is similar to CMA7 and CMA8 in that it accounts for carry-over within and before the observation window assuming that new medication is "banked" until needed (oversupply from previous events is used first, followed new medication supply). Yet, unlike these previous CMAs, it does not assume the medication is used as prescribed; in longitudinal studies with multiple CMA measures, this assumption may introduce additional variation in CMA estimates depending on when the observation window starts in relation to the previous medication event. A shorter time distance from the previous event (and longer to the first event in the observation window) results in higher values even if the number of gap days is the same, and it may also be that the patient has had a similar use pattern for that time interval, rather than perfect adherence followed by no medication use. CMA9 applies a different adjustment: it computes a ratio of days supply over each interval between two prescriptions and considers this applies for each day of that interval, up to 100% (moving oversupply to the next event interval). All medication events in the follow up window before observation window are considered for carry-over calculation. The last interval ends at the end of the follow-up window. Thus, it accounts for timing within the observation window, as well as before (but differently from CMA7 and CMA8), and excludes the remaining supply at the end of the observation window, if any.

The formula is

(number of days in the observation window, each weighted by the ratio of days supply applicable to their event interval) / (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" CMA7 (default value is FALSE), and an "alternative" CMA7b, 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).

Value

An S3 object of class CMA9 (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).

Examples

cma9 <- CMA9(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"
            );

CMA_per_episode constructor.

Description

Applies a given CMA to each treatment episode and constructs a CMA_per_episode object.

Usage

CMA_per_episode(
  CMA.to.apply,
  data,
  treat.epi = 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 = NA,
  consider.dosage.change = NA,
  medication.change.means.new.treatment.episode = TRUE,
  dosage.change.means.new.treatment.episode = FALSE,
  maximum.permissible.gap = 180,
  maximum.permissible.gap.unit = c("days", "weeks", "months", "years", "percent")[1],
  maximum.permissible.gap.append.to.episode = 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],
  return.inner.event.info = FALSE,
  date.format = "%m/%d/%Y",
  summary = "CMA per treatment episode",
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  return.mapping.events.episodes = FALSE,
  parallel.backend = c("none", "multicore", "snow", "snow(SOCK)", "snow(MPI)",
    "snow(NWS)")[1],
  parallel.threads = "auto",
  suppress.warnings = FALSE,
  suppress.special.argument.checks = TRUE,
  ...
)

Arguments

Details

CMA_per_episode first identifies the treatment episodes for the whole follo-up window (using the compute.treatment.episodes function), and then computes the given "simple" CMA for each treatment episode that intersects with the observation window. NB: the CMA is computed for the period of the episode that is part of the observations window; thus, if an episode starts earlier or ends later than the observation window, CMA will be computed for a section of that episode. Thus, as opposed to the "simple" CMAs 1 to 9, it returns a set of CMAs, with possibly more than one element.

It is highly similar to CMA_sliding_window which computes a CMA for a set of sliding windows.

Value

An S3 object of class CMA_per_episode 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).

• computed.CMA the class name of the computed CMA.

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column) and treatment episode, with columns:

  • ID.colname the patient ID as given by the ID.colname parameter.

  • episode.ID the unique treatment episode ID (within patients).

  • episode.start the treatment episode's start date (as a Date object).

  • end.episode.gap.days the corresponding gap days of the last event in this episode.

  • episode.duration the treatment episode's duration in days.

  • episode.end the treatment episode's end date (as a Date object).

  • CMA the treatment episode's estimated CMA.

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

See Also

CMA_sliding_window is very similar, computing a "simple" CMA for each of a set of same-size sliding windows. The "simple" CMAs that can be computed comprise CMA1, CMA2, CMA3, CMA4, CMA5, CMA6, CMA7, CMA8, CMA9, as well as user-defined classes derived from CMA0 that have a CMA component giving the estimated CMA per patient as a data.frame. If return.mapping.events.episodes is TRUE, then this also has a component mapping.episodes.to.events that gives the mapping between episodes and events as a data.table with the following columns:

• patid the patient ID.

• episode.ID the episode unique ID (increasing sequentially).

• event.index.in.data the event given by its row number in the data.

Examples

## Not run: 
cmaE <- CMA_per_episode(CMA="CMA1",
                        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=0,
                        observation.window.start=0,
                        observation.window.duration=365,
                        date.format="%m/%d/%Y"
                       );
## End(Not run)

CMA constructor for polypharmacy.

Description

Constructs a CMA (continuous multiple-interval measures of medication availability/gaps) object for polypharmacy.

Usage

CMA_polypharmacy(
  data = data,
  medication.groups = medication.class.colname,
  CMA.to.apply = NA,
  aggregate.first = TRUE,
  aggregation.method = NA,
  aggregation.method.arguments = NA,
  thresholds = NA,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  event.daily.dose.colname = NA,
  medication.class.colname = NA,
  carry.only.for.same.medication = NA,
  consider.dosage.change = NA,
  followup.window.start = 0,
  followup.window.start.unit = c("days", "weeks", "months", "years")[1],
  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 = "CMA for polypharmacy",
  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,
  suppress.special.argument.checks = TRUE,
  ...
)

Arguments

Value

An S3 object of class CMA_polypharmacy 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).

• aggregation.method the aggregation method to combine CMA values from different groups.

• computed.CMA the class name of the computed CMA.

• medication.groups a data.frame with medication groups and classes

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column) and sometimes treatment group, with columns:

  • ID.colname the patient ID as given by the ID.colname parameter.

  • medication.groups only when no aggregation method is used (aggregation.method = NA); the treatment group as given by the medication.groups parameter.

  • CMA the treatment episode's estimated CMA.

Examples

## Not run: 
CMA_PP <- CMA_polypharmacy(data = med.events.pp,
medication.groups = med.groups,
CMA.to.apply = "CMA7",
aggregate.first = TRUE, # aggregate before summarizing
aggregation.method = "mean", # compute mean of CMAs
aggregation.method.arguments = list(na.rm = TRUE), # remove NA's during calculation
thresholds = NA, # don't apply threshold
ID.colname="PATIENT_ID",
event.date.colname="DATE",
event.duration.colname="DURATION",
event.daily.dose.colname="PERDAY",
medication.class.colname="CATEGORY",
followup.window.start=0,
observation.window.start=180,
observation.window.duration=365,
carry.only.for.same.medication = TRUE);
## End(Not run)

CMA_sliding_window constructor.

Description

Applies a given CMA to each sliding window and constructs a CMA_sliding_window object.

Usage

CMA_sliding_window(
  CMA.to.apply,
  data,
  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 = NA,
  consider.dosage.change = NA,
  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],
  sliding.window.start = 0,
  sliding.window.start.unit = c("days", "weeks", "months", "years")[1],
  sliding.window.duration = 90,
  sliding.window.duration.unit = c("days", "weeks", "months", "years")[1],
  sliding.window.step.duration = 30,
  sliding.window.step.unit = c("days", "weeks", "months", "years")[1],
  sliding.window.no.steps = NA,
  return.inner.event.info = FALSE,
  date.format = "%m/%d/%Y",
  summary = "CMA per sliding window",
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  force.NA.CMA.for.failed.patients = TRUE,
  return.mapping.events.sliding.window = FALSE,
  parallel.backend = c("none", "multicore", "snow", "snow(SOCK)", "snow(MPI)",
    "snow(NWS)")[1],
  parallel.threads = "auto",
  suppress.warnings = FALSE,
  suppress.special.argument.checks = FALSE,
  ...
)

Arguments

Details

CMA_sliding_window first computes a set of fixed-size (possibly partly overlapping) sliding windows, each sliding to the right by a fixed timelag, and then, for each of them, it computes the given "simple" CMA. Thus, as opposed to the "simple" CMAs 1 to 9, it returns a set of CMAs, with possibly more than one element.

It is highly similar to CMA_per_episode which computes a CMA for a set of treatment episodes.

Value

An S3 object of class CMA_sliding_window 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).

• computed.CMA the class name of the computed CMA.

• CMA the data.frame containing the actual CMA estimates for each participant (the ID.colname column) and sliding window, with columns:

  • ID.colname the patient ID as given by the ID.colname parameter.

  • window.ID the unique window ID (within patients).

  • window.start the window's start date (as a Date object).

  • window.end the window's end date (as a Date object).

  • CMA the window's estimated CMA.

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

See Also

CMA_per_episode is very similar, computing a "simple" CMA for each of the treatment episodes. The "simple" CMAs that can be computed comprise CMA1, CMA2, CMA3, CMA4, CMA5, CMA6, CMA7, CMA8, CMA9, as well as user-defined classes derived from CMA0 that have a CMA component giving the estimated CMA per patient as a data.frame. If return.mapping.events.sliding.window is TRUE, then this also has an attribute mapping.windows.to.events that gives the mapping between episodes and events as a data.table with the following columns:

• patid the patient ID.

• window.ID the episode unique ID (increasing sequentially).

• event.index.in.data the event given by its row number in the data.

Examples

## Not run: 
cmaW <- CMA_sliding_window(CMA="CMA1",
                           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=0,
                           observation.window.start=0,
                           observation.window.duration=365,
                           sliding.window.start=0,
                           sliding.window.start.unit="days",
                           sliding.window.duration=90,
                           sliding.window.duration.unit="days",
                           sliding.window.step.duration=7,
                           sliding.window.step.unit="days",
                           sliding.window.no.steps=NA,
                           date.format="%m/%d/%Y"
                          );
## End(Not run)

callAdhereR.

Description

The function encapsulating all the logics that allows AdhereR to be called from any platform using the generic shell mechanism.

Usage

callAdhereR(shared.data.directory)

Arguments

Details

In most cases this should not be done directly by the user, but instead used by an appropriate wrapper on the client platform. It allows transparent use of AdhereR from virtually any platform or programming language for which an appropriate wrapper is provided. For more details see the vignette describing the included reference Python 3 wrapper.

Value

This function displays any messages to the console, tries to also write them to the Adherer-results.txt file in the shared.data.directory directory, and, when finished, forces R to quit with a given shell error code:

• 0 The processing ended without major errors;

• 1 General error (hopefully there are messages in the Adherer-results.txt file;

• 10 The directory shared.data.directory does not exit;

• 11 AdhereR does not have read access to the shared.data.directory directory;

• 12 AdhereR does not have write access to the shared.data.directory directory;

• 13 issues with the parameters file parameters.log;

• 14 issues with the data file dataset.csv;

• 15 plotting issues;

• 16 interactive plotting issues;

• 17 issues exporting the results.

Gap Days and Event (prescribing or dispensing) Intervals.

Description

For a given event (prescribing or dispensing) database, compute the gap days and event intervals in various scenarious.

Usage

compute.event.int.gaps(
  data,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  event.daily.dose.colname = NA,
  medication.class.colname = NA,
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  carryover.within.obs.window = FALSE,
  carryover.into.obs.window = FALSE,
  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.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",
  keep.window.start.end.dates = FALSE,
  remove.events.outside.followup.window = TRUE,
  keep.event.interval.for.all.events = FALSE,
  parallel.backend = c("none", "multicore", "snow", "snow(SOCK)", "snow(MPI)",
    "snow(NWS)")[1],
  parallel.threads = "auto",
  suppress.warnings = FALSE,
  suppress.special.argument.checks = FALSE,
  return.data.table = FALSE,
  ...
)

Arguments

Details

This should in general not be called directly by the user, but is provided as a basis for the extension to new CMAs.

Value

A data.frame or data.table extending the event.info parameter with:

• event.interval Or any other name given in event.interval.colname, containing the number of days between the start of the current event and the start of the next one.

• gap.days Or any other name given in gap.days.colname, containing the number of days when medication was not available for the current event (i.e., the "gap days").

• .FU.START.DATE,.FU.END.DATE if kept, the actual start and end dates of the follow-up window (after adjustments due to the various parameters).

• .OBS.START.DATE,.OBS.END.DATE if kept, the actual start and end dates of the observation window (after adjustments due to the various parameters).

• .EVENT.STARTS.BEFORE.OBS.WINDOW if kept, TRUE if the current event starts before the start of the observation window.

• .TDIFF1,.TDIFF2 if kept, various auxiliary time differences (in days).

• .EVENT.STARTS.AFTER.OBS.WINDOW if kept, TRUE if the current event starts after the end of the observation window.

• .CARRY.OVER.FROM.BEFORE if kept, the carry-over (if any) from the previous events.

• .EVENT.WITHIN.FU.WINDOW if kept, TRUE if the current event is within the follow-up window.

Compute Treatment Episodes.

Description

For a given event (prescribing or dispensing) database, compute the treatment episodes for each patient in various scenarious.

Usage

compute.treatment.episodes(
  data,
  ID.colname = NA,
  event.date.colname = NA,
  event.duration.colname = NA,
  event.daily.dose.colname = NA,
  medication.class.colname = NA,
  carryover.within.obs.window = TRUE,
  carry.only.for.same.medication = TRUE,
  consider.dosage.change = TRUE,
  medication.change.means.new.treatment.episode = TRUE,
  dosage.change.means.new.treatment.episode = FALSE,
  maximum.permissible.gap = 90,
  maximum.permissible.gap.unit = c("days", "weeks", "months", "years", "percent")[1],
  maximum.permissible.gap.append.to.episode = FALSE,
  followup.window.start = 0,
  followup.window.start.unit = c("days", "weeks", "months", "years")[1],
  followup.window.duration = 365 * 2,
  followup.window.duration.unit = c("days", "weeks", "months", "years")[1],
  event.interval.colname = "event.interval",
  gap.days.colname = "gap.days",
  return.mapping.events.episodes = FALSE,
  date.format = "%m/%d/%Y",
  parallel.backend = c("none", "multicore", "snow", "snow(SOCK)", "snow(MPI)",
    "snow(NWS)")[1],
  parallel.threads = "auto",
  suppress.warnings = FALSE,
  suppress.special.argument.checks = FALSE,
  return.data.table = FALSE,
  ...
)

Arguments

Details

This should in general not be called directly by the user, but is provided as a basis for the extension to new CMAs.

For the last treatment episode, the gap is considered only when longer than the maximum permissible gap. Please note the following:

• episode starts at first medication event for a particular medication,

• episode ends on the day when the last supply of that medication finished or if a period longer than the permissible gap preceded the next medication event, or at the end of the FUW,

• end episode gap days represents either the number of days after the end of the treatment episode (if medication changed, or if a period longer than the permissible gap preceded the next medication event) or at the end of (and within) the episode, i.e. the number of days after the last supply finished (if no other medication event followed until the end of the FUW),

• the duration of the episode is the interval between the episode start and episode end (and may include the gap days at the end, in the latter condition described above),

• the number of gap days after the end of the episode can be computed as all values larger than the permissible gap and 0 otherwise,

• if medication change starts new episode, then previous episode ends when the last supply is finished (irrespective of the length of gap compared to a maximum permissible gap); any days before the date of the new medication supply are considered a gap; this maintains consistency with gaps between episodes (whether they are constructed based on the maximum permissible gap rule or the medication change rule).

Value

A data.frame or data.table with the following columns (or NULL if no treatment episodes could be computed):

• patid the patient ID.

• episode.ID the episode unique ID (increasing sequentially).

• episode.start the episode start date.

• end.episode.gap.days the corresponding gap days of the last event in this episode.

• episode.duration the episode duration in days.

• episode.end the episode end date.

If mapping.episodes.to.events is TRUE, then this also has an attribute mapping.episodes.to.events that gives the mapping between episodes and events as a data.table with the following columns:

• patid the patient ID.

• episode.ID the episode unique ID (increasing sequentially).

• event.index.in.data the event given by its row number in the data.

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

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)

Cover special periods.

Description

Identifies special periods that are in proximity to already covered durations and adds additional events for these durations.

Usage

cover_special_periods(
  events.data,
  special.periods.data,
  ID.colname,
  medication.class.colnames,
  disp.date.colname,
  disp.start.colname,
  episode.start.colname,
  episode.end.colname,
  duration.colname,
  days.before,
  days.after,
  date.format,
  suppress.warnings = FALSE,
  return.data.table = FALSE,
  ...
)

Arguments

Details

Special periods may appear as gaps, possibly leading to underestimation of implementation or even assumption of discontinuation and non-persistence. To consider such periods as covered, this function adds additional durations, for example when it is assumed that hospitalized patients are adherent during the hospitalization period. This function should be used after pruning with prune_event_durations.

Value

A data.frame or data.table, the events.data with the additional durations for special periods covered.

Examples

## Not run: 
# select medication class of interest and compute event durations
disp_data <- durcomp.dispensing[ID == 3 & grepl("J01EE01", ATC.CODE)]
presc_data <- durcomp.prescribing[ID == 3 & grepl("J01EE01", ATC.CODE)]

event_durations_list <- compute_event_durations(disp.data = disp_data,
                                                presc.data = presc_data,
                                                special.periods.data = durcomp.hospitalisation,
                                                special.periods.method = "carryover",
                                                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 = "carryover",
                                                suppress.warnings = FALSE,
                                                return.data.table = TRUE,
                                                progress.bar = FALSE)

event_durations <- prune_event_durations(event_durations_list,
                                         include = c("special periods"),
                                         medication.class.colnames = "ATC.CODE",
                                         days.within.out.date.1 = 7,
                                         days.within.out.date.2 = 30,
                                         keep.all = TRUE)

# cover special periods
special_periods <- event_durations_list$special_periods
event_durations_covered <- cover_special_periods(events.data = event_durations,
                                                 special.periods.data = special_periods,
                                                 ID.colname = "ID",
                                                 medication.class.colnames = "ATC.CODE",
                                                 disp.start.colname = "DISP.START",
                                                 duration.colname = "DURATION",
                                                 days.before = 7,
                                                 days.after = 7,
                                                 date.format = "%Y-%m-%d")
       
## End(Not run)

Example dispensing events for 16 patients.

Description

A sample dataset containing dispensing events (one per row) for 16 patients over a period of roughly 24 months (1794 events in total). This is the appropriate format to compute event durations with the compute_event_durations function. Each row represents an individual dispensing record for a specific dose of a specific medication for a patient at a given date. More than one column to group medications can be supplied (such as ATC code, Form and Unit).

Usage

durcomp.dispensing

Format

A data frame with 1794 rows and 6 variables:

ID

integer here; patient unique identifier. Can also be string.

DATE.DISP

Date here;the dispensing event date, by default in the yyyy-mm-dd format. Can also be string.

ATC.CODE

character; the medication type, according to the WHO ATC classification system. This can be a researcher-defined classification depending on study aims (e.g., based on therapeutic use, mechanism of action, chemical molecule, or pharmaceutical formulation). The compute_event_durations function will match prescribed medication to dispensed medications based on this variable.

UNIT

integer; the unit of the dispensed dose. This is optional and can be used as a separate variable to match between prescription and dispensing events.

FORM

character; the galenic form of the dispensed preparation. This is optional and can be used as a separate variable to match between prescription and dispensing events.

TOTAL.DOSE

numeric; the total dispensed dose supplied at this medication event (e.g., 5000 for 10 tables of 500 mg).

Example special periods for 10 patients.

Description

A sample dataset containing special periods (one per row) for 10 patients over a period of roughly 18 months (28 events in total). This is the appropriate format to compute event durations with the compute_event_durations function. Each row represents an individual special period of type "hospitalization" of a patient for whom event durations should be calculated. Besides hospitalizations, this could cover other situations where medication use may differ, e.g. during incarcerations or holidays. All column names must match the format provided in this example.

Usage

durcomp.hospitalisation

Format

A data frame with 28 rows and 3 variables:

ID

Integer here; patient unique identifier. Can also be string.

DATE.IN

Date here;the start of the hospitalization period, by default in the yyyy-mm-dd format.Can also be string.

DATE.OUT

Date;the end of the hospitalization period, by default in the yyyy-mm-dd format. Can also be string.

Example prescription events for 16 patients.

Description

A sample dataset containing prescription events (one per row) for 16 patients over a period of roughly 15 months (1502 events in total). This is the appropriate format to compute event durations with the compute_event_durations function. Each row represents an individual prescription record for a specific dose of a specific medication for a patient at a given date. Visit number and Duration are optional, and more than one column to group medications can be supplied (such as ATC Code, Form or Unit).

Usage

durcomp.prescribing

Format

A data table with 1502 rows and 8 variables:

ID

integer here; patient unique identifier. Can also be string.

DATE.PRESC

Date here;the prescription event date, by default in the yyyy-mm-dd format. Can also be string.

VISIT

integer; the consecutive number of the prescription instances. This column is optional and will be generated internally when not supplied. It is used to identify treatment interruptions.

ATC.CODE

character; the medication type, according to the WHO ATC classification system. This can be a researcher-defined classification depending on study aims (e.g., based on therapeutic use, mechanism of action, chemical molecule, or pharmaceutical formulation). The compute_event_durations function will match prescribed medication to dispensed medications based on this variable.

FORM

character; the galenic form of the prescribed preparation. This is optional and can be used as a separate variable to match between prescription and dispensing events.

UNIT

integer; the unit of the prescribed dose. This is optional and can be used as a separate variable to match between prescription and dispensing events.

PRESC.DURATION

numeric; the duration (in days) for which the prescription is intended. Can be NA if the prescription is continuous without a fixed end date.

DAILY.DOSE

numeric; the daily dose prescribed during this event (e.g., 50 for 1 tablet of 50 mg per day or 25 for 1 tablet of 50 mg every two days).

Get the actual plotting area.

Description

Returns the actual plotting area rectangle in plotting coordinates.

Usage

get.event.plotting.area(
  plot.type = c("baseR", "SVG")[1],
  suppress.warnings = FALSE
)

Arguments

Details

This is intended for advanced users only.

Value

A numeric vector with components x.min, x.max, y.min and y.max, or NULL in case of error.

Get the legend plotting area.

Description

Returns the legend plotting area rectangle in plotting coordinates (if any).

Usage

get.legend.plotting.area(
  plot.type = c("baseR", "SVG")[1],
  suppress.warnings = FALSE
)

Arguments

Details

This is intended for advanced users only.

Value

A numeric vector with components x.min, x.max, y.min and y.max, or NULL in case of error or no legend being shown.

Get info about the plotted events.

Description

Returns a data.frame where each row contains info about one plotted event; the order of the rows reflects the y-axis (first row on bottom).

Usage

get.plotted.events(plot.type = c("baseR", "SVG")[1], suppress.warnings = FALSE)

Arguments

Details

This is intended for advanced users only.

Value

A data.frame that, besides the info about each event, also contains info about:

• the corresponding follow-up and observation windows (and, for CMA8, the "real" observation window), given as the corners of the area .X...START, .X...END, .Y...START and .Y...END (where the mid dot stands for FUW, OW and ROW, respectively).

• the area occupied by the graphic representation of the event given by its four corners .X.START, .X.END, .Y.START and .Y.END, as well as the line width .EV.LWD.

• the dose text's (if any) position (.X.DOSE, .Y.DOSE) and font size .FONT.SIZE.DOSE.

• if event corvered and not covered are plotted, also give their areas as .X.EVC.START, .X.EVC.END, .Y.EVC.START, .Y.EVC.END, .X.EVNC.START, .X.EVNC.END, .Y.EVNC.START and .Y.EVNC.END.

• the continuation lines area as .X.CNT.START, .X.CNT.END, .Y.CNT.START and .Y.CNT.END.

• and the corresponding summary CMA (if any) given as the area .X.SCMA.START, .X.SCMA.END, .Y.SCMA.START and .Y.SCMA.END.

Please note that even if with follow-up and ("real") observation window, and the summary CMA info is repeated for each event, they really make sense at the level of the patient.

Examples

cma7 <- CMA7(data=med.events[med.events$PATIENT_ID %in% c(1,2),],
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             event.daily.dose.colname="PERDAY",
             medication.class.colname="CATEGORY",
             followup.window.start=0,
             followup.window.start.unit="days",
             followup.window.duration=2*365,
             followup.window.duration.unit="days",
             observation.window.start=30,
             observation.window.start.unit="days",
             observation.window.duration=365,
             observation.window.duration.unit="days",
             date.format="%m/%d/%Y",
             summary="Base CMA");
plot(cma7);
tmp <- get.plotted.events();
head(tmp);
# "Mask" the first event:
rect(tmp$.X.START[1], tmp$.Y.START[1]-0.5, tmp$.X.END[1], tmp$.Y.END[1]+0.5,
     col=adjustcolor("white",alpha.f=0.75), border="black");
# "Mask" the first patient's summary CMA:
rect(tmp$.X.SCMA.START[1], tmp$.Y.SCMA.START[1],
     tmp$.X.SCMA.END[1], tmp$.Y.SCMA.END[1],
     col=adjustcolor("white",alpha.f=0.75), border="black");

Get info about the plotted partial CMAs.

Description

Returns a data.frame where each row contains info about one plotted partial CMA (partial CMAs make sense only for "complex" CMAs, i.e., per episode and sliding windows).

Usage

get.plotted.partial.cmas(
  plot.type = c("baseR", "SVG")[1],
  suppress.warnings = FALSE
)

Arguments

Details

This is intended for advanced users only.

Value

A data.frame that contains info about:

• the patient ID (pid) to which the partial CMA belongs.

• the type of partial CMA (see the help for plotting "complex" CMAs).

• the corners of the whole area covered by the partial CMA plot given as x.region.start, y.region.start, x.region.end and y.region.end.

• for each element of the partial CMA plot, its area as x.partial.start, y.partial.start, x.partial.end and y.partial.end.

Please note that this contains one row per partial CMA element (e.g., if plotting stacked, one row for each rectangle).

Access the actual CMA estimate from a CMA object.

Description

Retrieve the actual CMA estimate(s) encapsulated in a simple, per episode, or sliding window CMA object.

Usage

getCMA(
  x,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID"
)

Arguments

Value

a data.frame containing the CMA estimate(s).

Examples

cma1 <- CMA1(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
getCMA(cma1);
## Not run: 
cmaE <- CMA_per_episode(CMA="CMA1",
                        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=0,
                        observation.window.start=0,
                        observation.window.duration=365,
                        date.format="%m/%d/%Y"
                       );
getCMA(cmaE);
## End(Not run)

getCallerWrapperLocation.

Description

This function returns the full path to where the various wrappers that can call AdhereR are installed.

Usage

getCallerWrapperLocation(callig.platform = c("python3")[1], full.path = FALSE)

Arguments

Details

In most cases, these wrappers are one or more files in the calling language that may be directly used as such. For more details see the vignette describing the included reference Python 3 wrapper.

Value

The full path to the requested wrapper or NULL if none exists.

Access the event info from a CMA object.

Description

Retrieve the event info encapsulated in a simple, per episode, or sliding window CMA object.

Usage

getEventInfo(
  x,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID"
)

Arguments

Value

a data.frame containing the CMA estimate(s).

Examples

cma1 <- CMA1(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
getEventInfo(cma1);

getEventsToEpisodesMapping

Description

This function returns the event-to-episode mapping, if this information exists.

Usage

getEventsToEpisodesMapping(x)

Arguments

Details

There are cases where it is interesting to know which events belong to which episodes and which events have been actually used in computing the simple CMA for each episode. This information can be returned by compute.treatment.episodes() and CMA_per_episode() if the parameter return.mapping.events.episodes is set to TRUE.

Value

The mapping between events and episodes, if it exists either as the attribute mapping.episodes.to.events of the data.frame or as the mapping.episodes.to.events component of the CMA_per_episode object object, or NULL otherwise.

getEventsToSlidingWindowsMapping

Description

This function returns the event-to-sliding-window mapping, if this information exists.

Usage

getEventsToSlidingWindowsMapping(x)

Arguments

Details

There are cases where it is interesting to know which events belong to which sliding windows and which events have been actually used in computing the simple CMA for each sliding window This information can be returned by CMA_sliding_window() if the parameter return.mapping.events.episodes is set to TRUE.

Value

The mapping between events and episodes, if it exists as the mapping.windows.to.events component of the CMA_sliding_window object object, or NULL otherwise.

Access the inner event info from a complex CMA object.

Description

Retrieve the event info encapsulated in a complex (i.e., per episode or sliding window) CMA object.

Usage

getInnerEventInfo(
  x,
  flatten.medication.groups = FALSE,
  medication.groups.colname = ".MED_GROUP_ID"
)

Arguments

Value

a data.frame containing the CMA estimate(s).

Access the medication groups of a CMA object.

Description

Retrieve the medication groups and the observations they refer to (if any).

Usage

getMGs(x)

Arguments

Value

a list with two members:

• defs A data.frame containing the names and definitions of the medication classes; please note that there is an extra class __ALL_OTHERS__ containing all the observations not selected by any of the explicitly given medication classes.

• obs A logical matrix where the columns are the medication classes (the last being __ALL_OTHERS__), and the rows the observations in the x's data; element (i,j) is TRUE iff observation j was selected by medication class i.

Access last adherence plot info.

Description

Returns the full info the last adherence plot, to be used to modify and/or to add new elements to this plot.

Usage

last.plot.get.info()

Details

This is intended for advanced users only. It may return NULL if no plotting was generated yet, but if one was, a list contaning one named element for each type of plot produced (currently only baseR and SVG are used). For all types of plots there are a set of mapping functions useful for transforming events in plotting coordinates: .map.event.x(x) takes a number of days x, .map.event.date(d, adjust.for.earliest.date=TRUE) takes a Date d (and implictely adjusts for the earilerst date plotted), and .map.event.y(y) takes a row ("event" number) y. Besides the shared elements (see the returned value), there are specific ones as well. For baseR, the members old.par and used.par contain the original (pre-plot) par() environment and the one used within plot(), respectively, in case these need restoring.

Value

A list (possibly empty) contaning one named element for each type of plot produced (currently only baseR and SVG). Each may contain shared and specific fields concerning:

• the values of the parameters with which plot() was invoked.

• actual plot size and other characteristics.

• actual title, axis names and labels and their position and size.

• legend size, position and size and position of its components.

• expanded cma$data contaning, for each event, info about its plotting, including the corresponding fullow-uo and observation windows, event start and end, dose text (if any) and other graphical elements.

• position, size of the partial CMAs (if any) and of their components.

• position, size of the plotted CMAs (if any) and of their components.

• rescaling function(s) useful for mapping events to plotting coordinates.

Examples

cma7 <- CMA7(data=med.events[med.events$PATIENT_ID %in% c(1,2),],
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             event.daily.dose.colname="PERDAY",
             medication.class.colname="CATEGORY",
             followup.window.start=0,
             followup.window.start.unit="days",
             followup.window.duration=2*365,
             followup.window.duration.unit="days",
             observation.window.start=30,
             observation.window.start.unit="days",
             observation.window.duration=365,
             observation.window.duration.unit="days",
             date.format="%m/%d/%Y",
             summary="Base CMA");
plot(cma7);
tmp <- last.plot.get.info();
names(tmp);
tmp$baseR$legend$box; # legend position and size
head(tmp$baseR$cma$data); # events + plotting info
# Add a transparent blue rect between days 270 and 900:
rect(tmp$baseR$.map.event.x(270), tmp$baseR$.map.event.y(1-0.5),
     tmp$baseR$.map.event.x(900), tmp$baseR$.map.event.y(nrow(tmp$baseR$cma$data)+0.5),
     col=adjustcolor("blue",alpha.f=0.5), border="blue");
# Add a transparent rect rect between dates 03/15/2036 and 03/15/2037:
rect(tmp$baseR$.map.event.date(as.Date("03/15/2036", format="%m/%d/%Y")),
     tmp$baseR$.map.event.y(1-0.5),
     tmp$baseR$.map.event.date(as.Date("03/15/2037", format="%m/%d/%Y")),
     tmp$baseR$.map.event.y(nrow(tmp$baseR$cma$data)+0.5),
     col=adjustcolor("red",alpha.f=0.5), border="blue");

Map from event to plot coordinates.

Description

Maps the (x,y) coordinates in the event space to the plotting space.

Usage

map.event.coords.to.plot(
  x = NA,
  y = NA,
  x.is.Date = FALSE,
  x.date.format = "%m/%d/%Y",
  adjust.for.earliest.date = TRUE,
  plot.type = c("baseR", "SVG")[1],
  suppress.warnings = FALSE
)

Arguments

Details

This is intended for advanced users only. In the event space, the x coordinate can be either given as the number of days since the first plotted event, or as an actual calendar date (either as a Date object or a string with a given format; a date may or may not be corrected relative to the first displayed date). On the y coordinate, the plotting is divided in equally spaced rows, each row corresponding to a single event or an element of a partial CMA plot (one can specify in between rows using fractions). Any or both of x and y can be missing.

Value

A numeric vector with x and y components giving the plotting coordinates, or NULL in case of error.

Examples

cma7 <- CMA7(data=med.events[med.events$PATIENT_ID %in% c(1,2),],
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             event.daily.dose.colname="PERDAY",
             medication.class.colname="CATEGORY",
             followup.window.start=0,
             followup.window.start.unit="days",
             followup.window.duration=2*365,
             followup.window.duration.unit="days",
             observation.window.start=30,
             observation.window.start.unit="days",
             observation.window.duration=365,
             observation.window.duration.unit="days",
             date.format="%m/%d/%Y",
             summary="Base CMA");
plot(cma7);
# Add a transparent blue rect:
rect(map.event.coords.to.plot(x=270),
     get.event.plotting.area()["y.min"]-1,
     map.event.coords.to.plot(x="03/15/2037", x.is.Date=TRUE, x.date.format="%m/%d/%Y"),
     get.event.plotting.area()["y.max"]+1,
     col=adjustcolor("blue",alpha.f=0.5), border="blue");

Example medication events records for 100 patients.

Description

An artificial dataset containing medication events (one per row) for 100 patients (1080 events in total). This is the dataset format appropriate for medication adherence analyses performed with the R package AdhereR. Medication events represent individual records of prescribing or dispensing a specific medication for a patient at a given date. Dosage and medication type is optional (only needed if calculation of adherence or persistence takes into account changes in dosage and type of medication).

Usage

med.events

Format

A data frame with 1080 rows and 5 variables:

PATIENT_ID

integer here; patient unique identifier. Can also be string

.

DATE

character;the medication event date, by default in the mm/dd/yyyy format. It may represent a prescribing or dispensing date.

PERDAY

integer; the daily dosage prescribed for the medication supplied at this medication event (i.e. how many doses should be taken daily according to the prescription). This column is optional, as it is not considered in all functions but may be relevant for specific research or clinical contexts. All values should be > 0.

CATEGORY

character; the medication type, here two placeholder labels, 'medA' and 'medB'. This is a researcher-defined classification depending on study aims (e.g., based on therapeutic use, mechanism of action, chemical molecule, or pharmaceutical formulation). This column is optional, as it is not considered in all functions but may be relevant for specific research or clinical contexts.

DURATION

integer; the medication event duration in days (i.e. how many days the mediation supplied would last if used as prescribed); may be available in the extraction or computed based on quantity supplied (the number of doses prescribed or dispensed on that occasion) and daily dosage. All values should be > 0.

Example of medication events with ATC codes.

Description

An artificial dataset containing medication events (one per row) for 16 patients (1564 events in total), containing ATC codes. This dataset is derived from the durcomp datasets using the compute_event_durations function. See @med.events for more details.

Usage

med.events.ATC

Format

A data frame with 1564 rows and 7 variables:

PATIENT_ID

the patient unique identifier.

DATE

the medication event date.

DURATION

the duration in days.

PERDAY

the daily dosage.

CATEGORY

the ATC code.

CATEGORY_L1

explicitation of the first field of the ATC code (e.g., "A"="ALIMENTARY TRACT AND METABOLISM").

CATEGORY_L2

explicitation of the first and second fields of the ATC code (e.g., "A02"="DRUGS FOR ACID RELATED DISORDERS").

Example of medication groups.

Description

An example defining 6 medication groups for med.events.ATC. It is a named character vector, where the names are the medication group unique names (e.g., "Vitamines") and the elements are the medication group definitions (e.g., "(CATEGORY_L2 == 'VITAMINS')"). The definitions are R logical expressions using column names and values that appear in the dataset, as well as references to other medication groups using the construction "NAME".

Usage

med.groups

Format

An object of class character of length 6.

Details

In the above example, "CATEGORY_L2" is a column name in the med.events.ATC dataset, and 'VITAMINS' one of its possible values, and which selects all events that have prescribed ATC codes "A11" (aka "VITAMINS"). Another example is "NotVita" defined as "(!Vitamines)", which selects all events that do not have Vitamines prescribed.

For more details, please see the acompanying vignette.

Plot CMA0 objects.

Description

Plots the events (prescribing or dispensing) data encapsulated in a basic CMA0 object.

Usage

## S3 method for class 'CMA0'
plot(
  x,
  ...,
  patients.to.plot = NULL,
  duration = NA,
  align.all.patients = FALSE,
  align.first.event.at.zero = FALSE,
  show.period = c("dates", "days")[2],
  period.in.days = 90,
  show.legend = TRUE,
  legend.x = "right",
  legend.y = "bottom",
  legend.bkg.opacity = 0.5,
  legend.cex = 0.75,
  legend.cex.title = 1,
  cex = 1,
  cex.axis = 0.75,
  cex.lab = 1,
  xlab = c(dates = "Date", days = "Days"),
  ylab = c(withoutCMA = "patient", withCMA = "patient (& CMA)"),
  title = c(aligned = "Event patterns (all patients aligned)", notaligned =
    "Event patterns"),
  col.cats = rainbow,
  unspecified.category.label = "drug",
  medication.groups.to.plot = NULL,
  medication.groups.separator.show = TRUE,
  medication.groups.separator.lty = "solid",
  medication.groups.separator.lwd = 2,
  medication.groups.separator.color = "blue",
  medication.groups.allother.label = "*",
  lty.event = "solid",
  lwd.event = 2,
  pch.start.event = 15,
  pch.end.event = 16,
  plot.events.vertically.displaced = TRUE,
  print.dose = FALSE,
  cex.dose = 0.75,
  print.dose.outline.col = "white",
  print.dose.centered = FALSE,
  plot.dose = FALSE,
  lwd.event.max.dose = 8,
  plot.dose.lwd.across.medication.classes = FALSE,
  col.continuation = "black",
  lty.continuation = "dotted",
  lwd.continuation = 1,
  col.na = "lightgray",
  highlight.followup.window = TRUE,
  followup.window.col = "green",
  highlight.observation.window = TRUE,
  observation.window.col = "yellow",
  observation.window.density = 35,
  observation.window.angle = -30,
  observation.window.opacity = 0.3,
  alternating.bands.cols = c("white", "gray95"),
  rotate.text = -60,
  force.draw.text = FALSE,
  bw.plot = FALSE,
  min.plot.size.in.characters.horiz = 0,
  min.plot.size.in.characters.vert = 0,
  suppress.warnings = FALSE,
  max.patients.to.plot = 100,
  export.formats = NULL,
  export.formats.fileprefix = "AdhereR-plot",
  export.formats.height = NA,
  export.formats.width = NA,
  export.formats.save.svg.placeholder = TRUE,
  export.formats.svg.placeholder.type = c("jpg", "png", "webp")[2],
  export.formats.svg.placeholder.embed = FALSE,
  export.formats.html.template = NULL,
  export.formats.html.javascript = NULL,
  export.formats.html.css = NULL,
  export.formats.directory = NA,
  generate.R.plot = TRUE,
  do.not.draw.plot = FALSE
)

Arguments

Details

The x-axis represents time (either in days since the earliest date or as actual dates), with consecutive events represented as ascending on the y-axis.

Each event is represented as a segment with style lty.event and line width lwd.event starting with a pch.start.event and ending with a pch.end.event character, coloured with a unique color as given by col.cats, extending from its start date until its end date. Consecutive events are thus represented on consecutive levels of the y-axis and are connected by a "continuation" line with col.continuation colour, lty.continuation style and lwd.continuation width; these continuation lines are purely visual guides helping to perceive the sequence of events, and carry no information about the availability of medication in this interval.

When several patients are displayed on the same plot, they are organized vertically, and alternating bands (white and gray) help distinguish consecutive patients. Implicitly, all patients contained in the cma object will be plotted, but the patients.to.plot parameter allows the selection of a subset of patients.

Examples

cma0 <- CMA0(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             event.daily.dose.colname="PERDAY",
             medication.class.colname="CATEGORY",
             followup.window.start=0,
             followup.window.start.unit="days",
             followup.window.duration=2*365,
             followup.window.duration.unit="days",
             observation.window.start=30,
             observation.window.start.unit="days",
             observation.window.duration=365,
             observation.window.duration.unit="days",
             date.format="%m/%d/%Y",
             summary="Base CMA");
plot(cma0, patients.to.plot=c("1","2"));

Plot CMA0-derived objects.

Description

Plots the event data and estimated CMA encapsulated in objects derived from CMA0.

Usage

## S3 method for class 'CMA1'
plot(
  x,
  ...,
  patients.to.plot = NULL,
  duration = NA,
  align.all.patients = FALSE,
  align.first.event.at.zero = FALSE,
  show.period = c("dates", "days")[2],
  period.in.days = 90,
  show.legend = TRUE,
  legend.x = "right",
  legend.y = "bottom",
  legend.bkg.opacity = 0.5,
  legend.cex = 0.75,
  legend.cex.title = 1,
  cex = 1,
  cex.axis = 0.75,
  cex.lab = 1,
  show.cma = TRUE,
  col.cats = rainbow,
  unspecified.category.label = "drug",
  medication.groups.to.plot = NULL,
  medication.groups.separator.show = TRUE,
  medication.groups.separator.lty = "solid",
  medication.groups.separator.lwd = 2,
  medication.groups.separator.color = "blue",
  medication.groups.allother.label = "*",
  lty.event = "solid",
  lwd.event = 2,
  pch.start.event = 15,
  pch.end.event = 16,
  show.event.intervals = TRUE,
  col.na = "lightgray",
  print.CMA = TRUE,
  CMA.cex = 0.5,
  plot.CMA = TRUE,
  CMA.plot.ratio = 0.1,
  CMA.plot.col = "lightgreen",
  CMA.plot.border = "darkgreen",
  CMA.plot.bkg = "aquamarine",
  CMA.plot.text = CMA.plot.border,
  highlight.followup.window = TRUE,
  followup.window.col = "green",
  highlight.observation.window = TRUE,
  observation.window.col = "yellow",
  observation.window.density = 35,
  observation.window.angle = -30,
  observation.window.opacity = 0.3,
  show.real.obs.window.start = TRUE,
  real.obs.window.density = 35,
  real.obs.window.angle = 30,
  print.dose = FALSE,
  cex.dose = 0.75,
  print.dose.outline.col = "white",
  print.dose.centered = FALSE,
  plot.dose = FALSE,
  lwd.event.max.dose = 8,
  plot.dose.lwd.across.medication.classes = FALSE,
  alternating.bands.cols = c("white", "gray95"),
  bw.plot = FALSE,
  rotate.text = -60,
  force.draw.text = FALSE,
  min.plot.size.in.characters.horiz = 0,
  min.plot.size.in.characters.vert = 0,
  max.patients.to.plot = 100,
  export.formats = NULL,
  export.formats.fileprefix = "AdhereR-plot",
  export.formats.height = NA,
  export.formats.width = NA,
  export.formats.save.svg.placeholder = TRUE,
  export.formats.svg.placeholder.type = c("jpg", "png", "webp")[2],
  export.formats.svg.placeholder.embed = FALSE,
  export.formats.directory = NA,
  export.formats.html.template = NULL,
  export.formats.html.javascript = NULL,
  export.formats.html.css = NULL,
  generate.R.plot = TRUE,
  do.not.draw.plot = FALSE
)

## S3 method for class 'CMA2'
plot(...)

## S3 method for class 'CMA3'
plot(...)

## S3 method for class 'CMA4'
plot(...)

## S3 method for class 'CMA5'
plot(...)

## S3 method for class 'CMA6'
plot(...)

## S3 method for class 'CMA7'
plot(...)

## S3 method for class 'CMA8'
plot(...)

## S3 method for class 'CMA9'
plot(...)

Arguments

Details

Please note that this function plots objects inheriting from CMA0 but not objects of type CMA0 itself (these are plotted by plot.CMA0).

The x-axis represents time (either in days since the earliest date or as actual dates), with consecutive events represented as ascending on the y-axis.

Each event is represented as a segment with style lty.event and line width lwd.event starting with a pch.start.event and ending with a pch.end.event character, coloured with a unique color as given by col.cats, extending from its start date until its end date. Superimposed on these are shown the event intervals and gap days as estimated by the particular CMA method, more precisely plotting the start and end of the available events as solid filled-in rectangles, and the event gaps as shaded rectangles.

The follow-up and the observation windows are plotted as an empty rectangle and as shaded rectangle, respectively (for some CMAs the observation window might be adjusted in which case the adjustment may also be plotted using a different shading).

The CMA estimates can be visually represented as well in the left side of the figure using bars (sometimes the estimates can go above 100%, in which case the maximum possible bar filling is adjusted to reflect this).

When several patients are displayed on the same plot, they are organized vertically, and alternating bands (white and gray) help distinguish consecutive patients. Implicitely, all patients contained in the cma object will be plotted, but the patients.to.plot parameter allows the selection of a subset of patients.

Finally, the y-axis shows the patient ID and possibly the CMA estimate as well.

Examples

cma1 <- CMA1(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
plot(cma1, patients.to.plot=c("1","2"));

Plot CMA_per_episode and CMA_sliding_window objects.

Description

Plots the event data and the estimated CMA per treatment episode and sliding window, respectively.

Usage

## S3 method for class 'CMA_per_episode'
plot(
  x,
  patients.to.plot = NULL,
  duration = NA,
  align.all.patients = FALSE,
  align.first.event.at.zero = FALSE,
  show.period = c("dates", "days")[2],
  period.in.days = 90,
  show.legend = TRUE,
  legend.x = "right",
  legend.y = "bottom",
  legend.bkg.opacity = 0.5,
  legend.cex = 0.75,
  legend.cex.title = 1,
  cex = 1,
  cex.axis = 0.75,
  cex.lab = 1,
  show.cma = TRUE,
  xlab = c(dates = "Date", days = "Days"),
  ylab = c(withoutCMA = "patient", withCMA = "patient (& CMA)"),
  title = c(aligned = "Event patterns (all patients aligned)", notaligned =
    "Event patterns"),
  col.cats = rainbow,
  unspecified.category.label = "drug",
  medication.groups.to.plot = NULL,
  medication.groups.separator.show = TRUE,
  medication.groups.separator.lty = "solid",
  medication.groups.separator.lwd = 2,
  medication.groups.separator.color = "blue",
  medication.groups.allother.label = "*",
  lty.event = "solid",
  lwd.event = 2,
  pch.start.event = 15,
  pch.end.event = 16,
  show.event.intervals = FALSE,
  show.overlapping.event.intervals = c("first", "last", "min gap", "max gap",
    "average")[1],
  plot.events.vertically.displaced = TRUE,
  print.dose = FALSE,
  cex.dose = 0.75,
  print.dose.outline.col = "white",
  print.dose.centered = FALSE,
  plot.dose = FALSE,
  lwd.event.max.dose = 8,
  plot.dose.lwd.across.medication.classes = FALSE,
  col.na = "lightgray",
  col.continuation = "black",
  lty.continuation = "dotted",
  lwd.continuation = 1,
  print.CMA = TRUE,
  CMA.cex = 0.5,
  plot.CMA = TRUE,
  plot.CMA.as.histogram = TRUE,
  plot.partial.CMAs.as = c("stacked", "overlapping", "timeseries")[1],
  plot.partial.CMAs.as.stacked.col.bars = "gray90",
  plot.partial.CMAs.as.stacked.col.border = "gray30",
  plot.partial.CMAs.as.stacked.col.text = "black",
  plot.partial.CMAs.as.timeseries.vspace = 7,
  plot.partial.CMAs.as.timeseries.start.from.zero = TRUE,
  plot.partial.CMAs.as.timeseries.col.dot = "darkblue",
  plot.partial.CMAs.as.timeseries.col.interval = "gray70",
  plot.partial.CMAs.as.timeseries.col.text = "firebrick",
  plot.partial.CMAs.as.timeseries.interval.type = c("none", "segments", "arrows",
    "lines", "rectangles")[2],
  plot.partial.CMAs.as.timeseries.lwd.interval = 1,
  plot.partial.CMAs.as.timeseries.alpha.interval = 0.25,
  plot.partial.CMAs.as.timeseries.show.0perc = TRUE,
  plot.partial.CMAs.as.timeseries.show.100perc = FALSE,
  plot.partial.CMAs.as.overlapping.alternate = TRUE,
  plot.partial.CMAs.as.overlapping.col.interval = "gray70",
  plot.partial.CMAs.as.overlapping.col.text = "firebrick",
  CMA.plot.ratio = 0.1,
  CMA.plot.col = "lightgreen",
  CMA.plot.border = "darkgreen",
  CMA.plot.bkg = "aquamarine",
  CMA.plot.text = CMA.plot.border,
  highlight.followup.window = TRUE,
  followup.window.col = "green",
  highlight.observation.window = TRUE,
  observation.window.col = "yellow",
  observation.window.opacity = 0.3,
  print.episode.or.sliding.window = FALSE,
  alternating.bands.cols = c("white", "gray95"),
  bw.plot = FALSE,
  rotate.text = -60,
  force.draw.text = FALSE,
  min.plot.size.in.characters.horiz = 0,
  min.plot.size.in.characters.vert = 0,
  max.patients.to.plot = 100,
  export.formats = NULL,
  export.formats.fileprefix = "AdhereR-plot",
  export.formats.height = NA,
  export.formats.width = NA,
  export.formats.save.svg.placeholder = TRUE,
  export.formats.svg.placeholder.type = c("jpg", "png", "webp")[2],
  export.formats.svg.placeholder.embed = FALSE,
  export.formats.html.template = NULL,
  export.formats.html.javascript = NULL,
  export.formats.html.css = NULL,
  export.formats.directory = NA,
  generate.R.plot = TRUE,
  do.not.draw.plot = FALSE,
  suppress.warnings = FALSE,
  ...
)

## S3 method for class 'CMA_sliding_window'
plot(
  x,
  patients.to.plot = NULL,
  duration = NA,
  align.all.patients = FALSE,
  align.first.event.at.zero = FALSE,
  show.period = c("dates", "days")[2],
  period.in.days = 90,
  show.legend = TRUE,
  legend.x = "right",
  legend.y = "bottom",
  legend.bkg.opacity = 0.5,
  legend.cex = 0.75,
  legend.cex.title = 1,
  cex = 1,
  cex.axis = 0.75,
  cex.lab = 1,
  show.cma = TRUE,
  xlab = c(dates = "Date", days = "Days"),
  ylab = c(withoutCMA = "patient", withCMA = "patient (& CMA)"),
  title = c(aligned = "Event patterns (all patients aligned)", notaligned =
    "Event patterns"),
  col.cats = rainbow,
  unspecified.category.label = "drug",
  medication.groups.to.plot = NULL,
  medication.groups.separator.show = TRUE,
  medication.groups.separator.lty = "solid",
  medication.groups.separator.lwd = 2,
  medication.groups.separator.color = "blue",
  medication.groups.allother.label = "*",
  lty.event = "solid",
  lwd.event = 2,
  pch.start.event = 15,
  pch.end.event = 16,
  show.event.intervals = FALSE,
  show.overlapping.event.intervals = c("first", "last", "min gap", "max gap",
    "average")[1],
  plot.events.vertically.displaced = TRUE,
  print.dose = FALSE,
  cex.dose = 0.75,
  print.dose.outline.col = "white",
  print.dose.centered = FALSE,
  plot.dose = FALSE,
  lwd.event.max.dose = 8,
  plot.dose.lwd.across.medication.classes = FALSE,
  col.na = "lightgray",
  col.continuation = "black",
  lty.continuation = "dotted",
  lwd.continuation = 1,
  print.CMA = TRUE,
  CMA.cex = 0.5,
  plot.CMA = TRUE,
  plot.CMA.as.histogram = TRUE,
  plot.partial.CMAs.as = c("stacked", "overlapping", "timeseries")[1],
  plot.partial.CMAs.as.stacked.col.bars = "gray90",
  plot.partial.CMAs.as.stacked.col.border = "gray30",
  plot.partial.CMAs.as.stacked.col.text = "black",
  plot.partial.CMAs.as.timeseries.vspace = 7,
  plot.partial.CMAs.as.timeseries.start.from.zero = TRUE,
  plot.partial.CMAs.as.timeseries.col.dot = "darkblue",
  plot.partial.CMAs.as.timeseries.col.interval = "gray70",
  plot.partial.CMAs.as.timeseries.col.text = "firebrick",
  plot.partial.CMAs.as.timeseries.interval.type = c("none", "segments", "arrows",
    "lines", "rectangles")[2],
  plot.partial.CMAs.as.timeseries.lwd.interval = 1,
  plot.partial.CMAs.as.timeseries.alpha.interval = 0.25,
  plot.partial.CMAs.as.timeseries.show.0perc = TRUE,
  plot.partial.CMAs.as.timeseries.show.100perc = FALSE,
  plot.partial.CMAs.as.overlapping.alternate = TRUE,
  plot.partial.CMAs.as.overlapping.col.interval = "gray70",
  plot.partial.CMAs.as.overlapping.col.text = "firebrick",
  CMA.plot.ratio = 0.1,
  CMA.plot.col = "lightgreen",
  CMA.plot.border = "darkgreen",
  CMA.plot.bkg = "aquamarine",
  CMA.plot.text = CMA.plot.border,
  highlight.followup.window = TRUE,
  followup.window.col = "green",
  highlight.observation.window = TRUE,
  observation.window.col = "yellow",
  observation.window.opacity = 0.3,
  print.episode.or.sliding.window = FALSE,
  alternating.bands.cols = c("white", "gray95"),
  bw.plot = FALSE,
  rotate.text = -60,
  force.draw.text = FALSE,
  min.plot.size.in.characters.horiz = 0,
  min.plot.size.in.characters.vert = 0,
  max.patients.to.plot = 100,
  export.formats = NULL,
  export.formats.fileprefix = "AdhereR-plot",
  export.formats.height = NA,
  export.formats.width = NA,
  export.formats.save.svg.placeholder = TRUE,
  export.formats.svg.placeholder.type = c("jpg", "png", "webp")[2],
  export.formats.svg.placeholder.embed = FALSE,
  export.formats.html.template = NULL,
  export.formats.html.javascript = NULL,
  export.formats.html.css = NULL,
  export.formats.directory = NA,
  generate.R.plot = TRUE,
  do.not.draw.plot = FALSE,
  suppress.warnings = FALSE,
  ...
)

Arguments

Details

The x-axis represents time (either in days since the earliest date or as actual dates), with consecutive events represented as ascending on the y-axis.

Each event is represented as a segment with style lty.event and line width lwd.event starting with a pch.start.event and ending with a pch.end.event character, coloured with a unique color as given by col.cats, extending from its start date until its end date. Consecutive events are thus represented on consecutive levels of the y-axis and are connected by a "continuation" line with col.continuation colour, lty.continuation style and lwd.continuation width; these continuation lines are purely visual guides helping to perceive the sequence of events, and carry no information about the avilability of medicine in this interval.

Above these, the treatment episodes or the sliding windows are represented in a stacked manner from the earlieast (left, bottom of the stack) to the latest (right, top of the stack), each showing the CMA as percent fill (capped at 100% even if CMA values may be higher) and also as text.

The follow-up and the observation windows are plotted as empty an rectangle and as shaded rectangle, respectively (for some CMAs the observation window might be adjusted in which case the adjustment may also be plotted using a different shading).

The kernel density ("smoothed histogram") of the CMA estimates across treatment episodes/sliding windows (if more than 2) can be visually represented as well in the left side of the figure (NB, their horizontal scales may be different across patients).

When several patients are displayed on the same plot, they are organized vertically, and alternating bands (white and gray) help distinguish consecutive patients. Implicitely, all patients contained in the cma object will be plotted, but the patients.to.plot parameter allows the selection of a subset of patients.

Finally, the y-axis shows the patient ID and possibly the CMA estimate as well.

Any not explicitely defined arguments are passed to the simple CMA estimation and plotting function; therefore, for more info about possible estimation parameters plese see the help for the appropriate simple CMA, and for possible aesthetic tweaks, please see the help for their plotting.

See Also

See the simple CMA estimation CMA1 to CMA9 and plotting plot.CMA1 functions for extra parameters.

Examples

## Not run: 
cmaW <- CMA_sliding_window(CMA=CMA1,
                        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=0,
                        observation.window.start=0,
                        observation.window.duration=365,
                        sliding.window.start=0,
                        sliding.window.start.unit="days",
                        sliding.window.duration=90,
                        sliding.window.duration.unit="days",
                        sliding.window.step.duration=7,
                        sliding.window.step.unit="days",
                        sliding.window.no.steps=NA,
                        date.format="%m/%d/%Y"
                       );
plot(cmaW, patients.to.plot=c("1","2"));
cmaE <- CMA_per_episode(CMA=CMA1,
                        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=0,
                        observation.window.start=0,
                        observation.window.duration=365,
                        date.format="%m/%d/%Y"
                       );
plot(cmaE, patients.to.plot=c("1","2"));
## End(Not run)

Interactive exploration and CMA computation.

Description

Interactively plot a given patient's data, allowing the real-time exploration of the various CMAs and their parameters. It can use Rstudio's manipulate library or Shiny.

Usage

plot_interactive_cma(...)

Arguments

Details

This is merely a stub for the actual implementation in package AdhereRViz: it just checks if this package is installed and functional, in which case it calls the actual implementation, otherwise warns the user that AdhereRViz must be instaled.

Value

Nothing

See Also

Function plot_interactive_cma in package AdhereRViz.

Examples

## Not run: 
plot_interactive_cma(med.events,
                     ID.colname="PATIENT_ID",
                     event.date.colname="DATE",
                     event.duration.colname="DURATION",
                     event.daily.dose.colname="PERDAY",
                     medication.class.colname="CATEGORY");
## End(Not run)

Print CMA0 (and derived) objects.

Description

Prints and summarizes a basic CMA0, or derived, object.

Usage

## S3 method for class 'CMA0'
print(
  x,
  ...,
  inline = FALSE,
  format = c("text", "latex", "markdown"),
  print.params = TRUE,
  print.data = TRUE,
  exclude.params = c("event.info", "real.obs.windows"),
  skip.header = FALSE,
  cma.type = class(cma)[1]
)

## S3 method for class 'CMA1'
print(...)

## S3 method for class 'CMA2'
print(...)

## S3 method for class 'CMA3'
print(...)

## S3 method for class 'CMA4'
print(...)

## S3 method for class 'CMA5'
print(...)

## S3 method for class 'CMA6'
print(...)

## S3 method for class 'CMA7'
print(...)

## S3 method for class 'CMA8'
print(...)

## S3 method for class 'CMA9'
print(...)

## S3 method for class 'CMA_per_episode'
print(
  x,
  ...,
  inline = FALSE,
  format = c("text", "latex", "markdown"),
  print.params = TRUE,
  print.data = TRUE,
  exclude.params = c("event.info", "inner.event.info", "mapping.episodes.to.events"),
  skip.header = FALSE,
  cma.type = class(x)[1]
)

## S3 method for class 'CMA_sliding_window'
print(...)

Arguments

Details

Can produce output for the console (text), R Markdown or LaTeX, showing various types of information.

Examples

cma0 <- CMA0(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             event.daily.dose.colname="PERDAY",
             medication.class.colname="CATEGORY",
             followup.window.start=0,
             followup.window.start.unit="days",
             followup.window.duration=2*365,
             followup.window.duration.unit="days",
             observation.window.start=30,
             observation.window.start.unit="days",
             observation.window.duration=365,
             observation.window.duration.unit="days",
             date.format="%m/%d/%Y",
             summary="Base CMA");
cma0;
print(cma0, format="markdown");
cma1 <- CMA1(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
cma1;

Prune event durations.

Description

Flags or removes leftover supply durations after dosage changes, the end of a special period, or treatment interruption. The function accepts the raw list output of compute_event_durations and additional arguments to specify event durations that need to be removed.

Usage

prune_event_durations(
  data,
  include = c("special periods", "treatment interruptions", "dosage changes"),
  medication.class.colnames = data$medication.class.colnames,
  days.within.out.date.1,
  days.within.out.date.2,
  keep.all = TRUE,
  suppress.warnings = FALSE,
  return.data.table = FALSE,
  ...
)

Arguments

Details

Dosage changes, special periods, and treatment interruptions may lead to overestimation of implementation, e.g. if patients get a refill after discharge from hospital and don't continue to use their previous supply. Likewise, it may also lead to overestimation of persistence, e.g. when patients discontinue treatments after the end of a special period or treatment interruption.

Value

A data.frame or data.table, the pruned event_durations.

Examples

## Not run: 
# select medication class of interest and compute event durations

disp_data <- durcomp.dispensing[ID == 3 & grepl("J01EE01", ATC.CODE)]
presc_data <- durcomp.prescribing[ID == 3 & grepl("J01EE01", ATC.CODE)]

# compute event durations
event_durations_list <- compute_event_durations(disp.data = disp_data,
                                                presc.data = presc_data,
                                                special.periods.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 = "carryover",
                                                special.periods.method = "carryover",
                                                suppress.warnings = FALSE,
                                                return.data.table = TRUE,
                                                progress.bar = FALSE)

# prune event durations
event_durations <- prune_event_durations(event_durations_list,
                                         include = c("special periods"),
                                         medication.class.colnames = "ATC.CODE",
                                         days.within.out.date.1 = 7,
                                         days.within.out.date.2 = 30,
                                         keep.all = FALSE)
       
## End(Not run)

Restrict a CMA object to a subset of patients.

Description

Restrict a CMA object to a subset of patients.

Usage

subsetCMA(cma, patients, suppress.warnings)

Arguments

Value

a CMA object containing only the information for the given patients.

Examples

cma1 <- CMA1(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
getCMA(cma1);
cma1a <- subsetCMA(cma1, patients=c(1:3,7));
cma1a; getCMA(cma1a);

Computation of initiation times.

Description

Computes the time between the start of a prescription episode and the first dispensing event for each medication class.

Usage

time_to_initiation(
  presc.data = NULL,
  disp.data = NULL,
  ID.colname = NA,
  medication.class.colnames = NA,
  presc.start.colname = NA,
  disp.date.colname = NA,
  date.format = "%d.%m.%Y",
  suppress.warnings = FALSE,
  return.data.table = FALSE,
  ...
)

Arguments

Details

The period between the start of a prescription episode and the first dose administration may impact health outcomes differently than omitting doses once on treatment or interrupting medication for longer periods of time. Primary non-adherence (not acquiring the first prescription) or delayed initiation may have a negative impact on health outcomes. The function time_to_initiation calculates the time between the start of a prescription episode and the first dispensing event, taking into account multiple variables to differentiate between treatments.

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.

• episode.start the date of the first prescription event.

• first.disp the date of the first dispensing event.

• time.to.initiation the difference in days between the first dispensing date and the first prescription date.