define_analyses {mds}

Assess Analyses Definitions

Description

Define analyses based on an MD-PMS device-event data frame and, optionally, an MD-PMS exposure data frame. See Details for how to use.

Usage

define_analyses(
  deviceevents,
  device_level,
  event_level = NULL,
  exposure = NULL,
  date_level = "months",
  date_level_n = 1,
  covariates = "_none_",
  times_to_calc = NULL,
  invivo = FALSE,
  prior = NULL
)

Arguments

deviceevents

A device-events object of class mds_de, created by a call to deviceevent().

device_level

String value indicating the source device variable name to analyze by. If exposure is specified, exposure data will be matched by device_level. If a hierarchy of 2 or more are present, see Details for important information.

Example: If the deviceevents variable column is device_1 where the source variable name for device_1 is 'Device Code', specify device_level='Device Code'.

event_level

String value indicating the source event variable name to analyze by. Note that event_level is not matched to exposure. If a hierarchy of 2 or more are present, see Details for important information.

Example: If the deviceevents variable column is event_1 where the source variable name for event_1 is 'Event Code', specify event_level='Event Code'.

Default: NULL will not analyze by event.

exposure

Optional exposure object of class mds_e. See details for how exposure analyses definitions are handled.

Default: NULL will not consider inclusion of exposure.

date_level

String value for the primary date unit to analyze by. Can be either 'months' or 'days'.

Default: 'months'

date_level_n

Numeric value indicating the number of date_levels to analyze by.

Example: date_level='months' and date_level_n=3 indicates analysis on a quarterly level.

Default: 1

covariates

Character vector specifying names of covariates to also define analyses for. Acceptable names are covariate variables specified in deviceevents. If the covariate is a factor, additional subgroup analyses will be defined at each level of the factor. "_none_" specifies no covariates, while "_all_" are all covariates specified in deviceevents. See details for more.

Example: c("Country", "Region")

Default: "_none_" specifies no covariates.

times_to_calc

Integer value indicating the number of date units counting backwards from the latest date to define analyses for. If prior is specified, times_to_calc will be ignored.

Example 1: times_to_calc=12 with date_level="months" and date_level_n=1 defines analyses for the last year by month.

Example 2: times_to_calc=8 with date_level="months" and date_level_n=3 defines analyses for the 2 years by quarter.

Default: NULL will define analyses across all available time.

invivo

Logical value indicating whether to include time_invivo from deviceevents in the analysis definition. See details for more.

Default: FALSE will not include time_invivo in the analysis definition.

prior

Future placeholder, currently not used.

Details

define_analyses() is a prerequisite to calling time_series(). This function enumerates all possible analyses based on input device-event (deviceevent()) and, optionally, exposure (exposure()) data frames. An analysis is defined as a set of instructions specifying at minimum the device level, event level, the date range of analysis, and the date unit. Additional instructions include the covariate level, time in-vivo status, and exposure levels.

By separating the analysis enumeration (define_analyses()) from the generation of the time series (time_series()), the user may rerun the analyses on different datasets and/or filter the analyses to only those of interest.

The analyses definitions will always include rollup levels for each of device_level, event_level (if specified), and covariates. Rollups are analyses at all device, event, and/or covariate levels. These rollup analyses will be indicated by the keyword 'All' in the analysis definition.

When a hierarchy of 2 or more variables for either device_level or event_level are present in deviceevents, define_analyses() will enforce the 1-level-up parent level ONLY. Additional higher parent levels are not currently enforced, thus the user is advised to uniquely name the 1-level-up parent level. The parent level DOES NOT ROLLUP currently because the parent level is intended to separate disparate data and devices. This may change in the future.

If exposure is specified, any available match_levels will be used to calculate the appropriate timeframe for analyses. The exception are the special rollup analyses (see prior paragraph).

When covariates are specified, a special rollup analysis definition will always be defined that does not consider the covariates at all. This analysis can be identified by covariate='Data' and covariate_level='All' in the output mds_da object.

When covariates are specified and there is no variation in the distribution of covariate values (e.g. all males, all 10, all missing) in the device- and event-specific dataset, these specific analyses will be dropped.

When factor covariates are specified, covariate-level analyses may be defined two ways: 1) detect an overall covariate level effect, also known as a 3-dimensional analysis, and 2) subset the data by each level of the covariate, also known as a subgroup analysis. 1) will be denoted as covariate_level='All' in the output mds_da object, while 2) will specify the factor level in covariate_level.

If invivo=TRUE, define_analyses() will first verify if data exists in the time_invivo variable for the given device_level, event_level, and, if applicable, covariates level. If no data exists, invivo will be implicitly assigned to FALSE.

Value

A list of defined analyses of class mds_das. Each list item, indexed by a numeric key, defines a set of analyses for a unique combination of device, event, and covariate level. Each list item is of the class mds_da. Attributes of class mds_das are as follows:

date_level

Defined value for date_level

date_level_n

Defined value for date_level_n

device_level

Defined value for device_level

event_level

Defined value for event_level

times_to_calc

Defined value for times_to_calc

prior_used

Boolean for whether prior was specified.

timestamp

System time when the analyses were defined.

Examples

# Device-Events
de <- deviceevent(
  data_frame=maude,
  time="date_received",
  device_hierarchy=c("device_name", "device_class"),
  event_hierarchy=c("event_type", "medical_specialty_description"),
  key="report_number",
  covariates=c("region"),
  descriptors="_all_")
# Exposures
ex <- exposure(
  data_frame=sales,
  time="sales_month",
  device_hierarchy="device_name",
  match_levels="region",
  count="sales_volume")
# Defined Analyses - Simple example
da <- define_analyses(de, "device_name")
# Defined Analyses - Simple example with a quarterly analysis
da <- define_analyses(de, "device_name", date_level_n=3)
# Defined Analyses - Example with event type, exposures, and covariates
da <- define_analyses(de, "device_name", "event_type", ex, covariates="region")