define_analyses {mds} | R Documentation |
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 |
device_level |
String value indicating the source device variable name
to analyze by. If Example: If the |
event_level |
String value indicating the source event variable name to
analyze by. Note that Example: If the Default: |
exposure |
Optional exposure object of class Default: |
date_level |
String value for the primary date unit to analyze by. Can
be either Default: |
date_level_n |
Numeric value indicating the number of Example: Default: |
covariates |
Character vector specifying names of covariates to also
define analyses for. Acceptable names are covariate variables specified
in Example: Default: |
times_to_calc |
Integer value indicating the number of date units
counting backwards from the latest date to define analyses for. If
Example 1: Example 2: Default: |
invivo |
Logical value indicating whether to include Default: |
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")