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.
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
)A device-events object of class mds_de, created by
a call to deviceevent().
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'.
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.
Optional exposure object of class mds_e. See details
for how exposure analyses definitions are handled.
Default: NULL will not consider inclusion of exposure.
String value for the primary date unit to analyze by. Can
be either 'months' or 'days'.
Default: 'months'
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
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.
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.
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.
Future placeholder, currently not used.
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:
Defined value for date_level
Defined value for date_level_n
Defined value for device_level
Defined value for event_level
Defined value for times_to_calc
Boolean for whether prior was specified.
System time when the analyses were defined.
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.
# NOT RUN {
# 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")
# }
Run the code above in your browser using DataLab