Allow medication "types"/"classes" for plotting and estimation

[ddediu]

Implement a way allowing the definition of "types" or "classes" of medication (presumably statically defined before calling AdhereR) but that can be dynamically used (including through Shiny) to decide what to plot and use ofr estimating the CMAs.

[ddediu]

Accepted (provisional) proposal:

Allow medication "types"/"classes" for plotting and estimation (GitHub issue #133)

Idea: the user should be able to dynamically (i.e., on-the-fly, including in the Shiny interactive interface) include/exclude/group/order what medications are to be plotted and used for estimating CMA.

Proposal:
The user can include up to N (suggestions: N=3) columns in the data.frame containing the events, columns that define “types” (or “classes”) of medications. For example, we may have:

|PATIENT_ID | DATE | PERDAY | CATEGORY | DURATION | MED_CLASS_1 | MED_CLASS_2|
|-------------|-------|----------|--------------|-------------|-----------------|-----------------|
|1 | mm/dd/yyy | 4 | A | 30 | C1 | C1.1|
|1 | mm/dd/yyy | 2 | B | 15 | C2 | C2|
|2 | mm/dd/yyy | 4 | A | 25 | C1 | C1.1|
|2 | mm/dd/yyy | 1 | B | 10 | C2 | C2|
|2 | mm/dd/yyy | 1 | C | 30 | C1 | C1.2|
|3 | mm/dd/yyy | 3 | A | 20 | C1 | C1.1|
|3 | mm/dd/yyy | 2 | D | 10 | C3 | C3|

Where there are 2 extra columns, MED_CLASS_1 and MED_CLASS_2, that define types of medication. Please note that these can be hierarchical (i.e., all levels of MED_CLASS_2 are fully included within those of MED_CLASS_1) or not.

Then the user can tell AdhereR (through some extra parameters) that these columns exist and, more importantly, how to use them.
For this, the user can define logical combinations of the values in CATEGORY and the extra columns (here, MED_CLASS_1 and MED_CLASS_2), and numeric tests with PERDAY, DURATION and DATE, and inclusion/exclusion with PATEINT_ID. These logical combinations are defined outside the data.frame with the data and are passed to the estimation and plotting functions separately. This should allow a lot of flexibility and on-the-fly capability. The syntax follows the standard R syntax (in fact, it uses R to evaluate them in a restricted and secure environment).

There is one predefined group, "__ALL_OTHER__", containing all the medications not covered by the explicit group definitions (if any), but for this group there is no estimation of the CMA (if any) but is used only for plotting.

For example:
For estimation:

cma1 <- CMA1(…, medication.groups=c(“CLS1” = “(MED_CLASS_1 == ‘C1’ & CATEGORY != ‘A’)”, “CLS2” = “CATEGORY == ‘A’ & PERDAY > 3”), …)

defined two big classes, "CLS1" and "CLS2" and estimates CMA1 only for those observations included in them (i.e., a CMA1 for observations 5, and a different CMA1 for observations 1, 3).
For plotting:

plot(cma1, …, medication_groups_to_show=c(“CLS2”, “CLS1”))

In Shiny this would be implemented as a wizard that allows columns to be combined and/or expressions to be written…