| Title: | Medical Devices Surveillance |
|---|---|
| Description: | A set of core functions for handling medical device event data in the context of post-market surveillance, pharmacovigilance, signal detection and trending, and regulatory reporting. Primary inputs are data on events by device and data on exposures by device. Outputs include: standardized device-event and exposure datasets, defined analyses, and time series. |
| Authors: | Gary Chung [aut, cre] |
| Maintainer: | Gary Chung <[email protected]> |
| License: | GPL-3 |
| Version: | 0.3.2 |
| Built: | 2024-11-06 04:41:52 UTC |
| Source: | https://github.com/gchung05/mds |
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 )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 )
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. |
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.
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.
# 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")# 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")
Returns a data frame summarizing all defined analyses from the
mds_das object.
define_analyses_dataframe(inlist)define_analyses_dataframe(inlist)
inlist |
Object of class |
A data frame with each row representing an analysis.
Converts a data frame into a MD-PMS Device Event data frame.
deviceevent( data_frame, time, device_hierarchy, event_hierarchy, key = NULL, covariates = NULL, descriptors = NULL, time_invivo = NULL )deviceevent( data_frame, time, device_hierarchy, event_hierarchy, key = NULL, covariates = NULL, descriptors = NULL, time_invivo = NULL )
data_frame |
The input data frame requiring components specified in the remaining arguments. |
time |
Character name of date variable in Example: |
device_hierarchy |
Vector of character variable names representing the
device hierarchy in Example: |
event_hierarchy |
Vector of character variable names representing the
event hierarchy in Example: |
key |
Character name of (uniquely identifying) primary key variable in
Example: Default: |
covariates |
Vector of character variable names representing the
desired covariates to retain, all of which must be of class Example: Default: |
descriptors |
Vector of character variable names representing additional
descriptive variables that will not be used in any analyses but may be
recalled or displayed later during individual device-event review.
Example: Default: |
time_invivo |
Character name of numeric variable in IMPORTANT: If a call to Example: Default: |
When more than 2 variables are specified in either device_hierarchy
or event_hierarchy, it is important to note that a subsequent call to
define_analyses() currently only utilizes a maximum of 2 variables:
the lowest level and the 1-level-up parent. The user may enforce full
hierarchy in >2 variable cases by ensuring that the parent values are
uniquely named.
time_invivo can be thought of more generally as the time of
exposure of the device to the subject at the time of the event. The common
usage is duration of the implant in the patient at time of event, for an
implantable medical device.
A standardized MD-PMS data frame of class mds_de.
Rows are deduplicated. Attributes are as follows:
Original variable name for key
Original variable name for time
Vector of original variable names for
device_hierarchy with converted variable names correspondingly
named.
Vector of original variable names for
event_hierarchy with converted variable names correspondingly
named.
Vector of original variable names for
covariates with converted variable names correspondingly
named.
Vector of original variable names for
descriptors with converted variable names correspondingly
named.
# A barebones dataset de <- deviceevent(maude, "date_received", "device_name", "event_type") # With more variables and variable types 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_")# A barebones dataset de <- deviceevent(maude, "date_received", "device_name", "event_type") # With more variables and variable types 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_")
Converts a data frame into a MD-PMS Exposure data frame.
exposure( data_frame, time, device_hierarchy, event_hierarchy = NULL, key = NULL, match_levels = NULL, count = NULL )exposure( data_frame, time, device_hierarchy, event_hierarchy = NULL, key = NULL, match_levels = NULL, count = NULL )
data_frame |
The input data frame requiring components specified in the remaining arguments. |
time |
Character name of date variable in Example: |
device_hierarchy |
Vector of character variable names representing the
device hierarchy in Example: |
event_hierarchy |
Vector of character variable names representing the
event hierarchy in Example: Default: |
key |
Character name of (uniquely identifying) primary key variable in
Example: Default: |
match_levels |
Vector of character variable names in Example: Default: |
count |
Character name of exposure count variable in Example: Default: |
A standardized MD-PMS data frame of class mds_e.
Rows are deduplicated. Attributes are as follows:
Original variable name for key
Original variable name for time
Vector of original variable names for
device_hierarchy with converted variable names correspondingly
named.
Vector of original variable names for
event_hierarchy with converted variable names correspondingly
named.
Vector of variable names for grouping factors
Original variable name for count
# A barebones dataset ex <- exposure(sales, "sales_month", "device_name") # With more variables and variable types ex <- exposure( data_frame=sales, time="sales_month", device_hierarchy="device_name", match_levels="region", count="sales_volume")# A barebones dataset ex <- exposure(sales, "sales_month", "device_name") # With more variables and variable types ex <- exposure( data_frame=sales, time="sales_month", device_hierarchy="device_name", match_levels="region", count="sales_volume")
A dataset containing 535 events reported into the FDA MAUDE database on bone cement in 2017. Data were obtained via the openFDA API (https://open.fda.gov).
maudemaude
A data frame with 535 rows and 15 variables. Full variable
descriptions may be found on the FDA Device Reference Guide
(https://open.fda.gov). Note that region
is a simulated variable not present in MAUDE. Descriptions as follows:
Identifying number for the adverse event report.
Outcomes associated with the adverse event.
Date the report was received by the FDA.
Indicates whether or not a report was about the quality, performance or safety of a device.
Whether the report is about an incident where the use of the device is suspected to have resulted in an adverse outcome in a patient.
Source of the adverse event report.
The lot number found on the label or packaging material.
The exact model number found on the device label or accompanying packaging.
Device manufacturer name.
Device manufacturer country.
The trade or proprietary name of the suspect medical device as used in product labeling or in the catalog.
This is the proprietary name, or trade name, of the cleared device.
Regulation Medical Specialty is assigned based on the regulation (e.g. 21 CFR Part 888 is Orthopedic Devices).
A risk based classification system for all medical devices ((Federal Food, Drug, and Cosmetic Act, section 513)
A simulated, randomly assigned geographical region for package example purposes.
https://open.fda.gov/data/maude/
An example list of time series objects (class mds_ts) generated using
the mds package.
mds_tsmds_ts
A list of 3 elements each of class mds_ts
See ?maude and ?sales for source device-event and
exposure data. See ?mds::time_series for how to generate mds_ts
time series.
Quickly visualizes an MD-PMS times series of class mds_ts.
## S3 method for class 'mds_ts' plot(x, mode = "nA", xlab = "Time", ylab = "Count", main = NULL, ...)## S3 method for class 'mds_ts' plot(x, mode = "nA", xlab = "Time", ylab = "Count", main = NULL, ...)
x |
An object of class |
mode |
Series to plot. Valid values are: Default: |
xlab |
x-axis label #' Default: |
ylab |
y-axis label Default: |
main |
Plot title Default: |
... |
Further arguments to pass onto |
mode values defined as follows. Note: The following
definitions use a device-event pair as a working example, however it may also
be a covariate-device pair.
Counts of the device-event pair.
Counts of the device for all other events.
Counts of all other devices for the event.
Counts of all other devices for all other events.
Counts of exposure for the device-event pair.
A crude rate, calculated as the device-event counts pair divided by the exposure counts.
A dataset containing simulated monthly sales by device and country for
devices reported in the maude dataset. For package usage examples,
this data serves as a proxy for exposures. Data were generated using a
random normal distribution weighted by the number of reported events by
device and country.
salessales
A data frame with 360 rows and 4 variables:
Name of the device mapped from the maude dataset.
Geographical region mapped from the maude dataset.
The month of sales.
The volume of sales.
Random normal distribution using rnorm().
define_analyses() call.Summarize a Collection of MD-PMS Defined Analyses
Prints basic counts and date ranges by various analysis factors as defined in
the original define_analyses() call.
## S3 method for class 'mds_das' summary(object, ...)## S3 method for class 'mds_das' summary(object, ...)
object |
A MD-PMS Defined Analyses object of class |
... |
Additional arguments affecting the summary produced |
List of analyses counts and date ranges.
Creates time series data frame(s) from defined analysis/analyses
(define_analyses()), device-event data frame
(deviceevent()), and optionally, exposure data frame
(exposure()). If analysis includes covariates or time in-vivo, creates
the relevant supporting data frame.
time_series(analysis, ...) ## S3 method for class 'list' time_series(analysis, ...) ## S3 method for class 'mds_das' time_series(analysis, ...) ## S3 method for class 'mds_da' time_series(analysis, deviceevents, exposure = NULL, use_hierarchy = T, ...)time_series(analysis, ...) ## S3 method for class 'list' time_series(analysis, ...) ## S3 method for class 'mds_das' time_series(analysis, ...) ## S3 method for class 'mds_da' time_series(analysis, deviceevents, exposure = NULL, use_hierarchy = T, ...)
analysis |
A defined analysis object of class |
... |
Further arguments for future work. |
deviceevents |
A device-event data frame of class |
exposure |
Optional exposure data frame of class Default: |
use_hierarchy |
Deprecated - do not use. Logical value indicating whether device and event hierarchies should be used in counting contingency tables for disproportionality analysis. |
A standardized MD-PMS time series data frame of class mds_ts.
The data frame contains, by defined date levels, the following columns:
Count of the device & event level of interest. If covariate analysis is indicated, this will be at the covariate & device level of interest.
Optional. Count of the device & non-event, or if covariate analysis,
covariate & non-device. nB will be missing if this is an
'All' level analysis.
Optional. Count of the non-device & event, or if covariate analysis,
non-covariate & device. nC will be missing if this is an
'All' level analysis.
Optional. Count of the non-device & non-event, or if covariate analysis,
non-covariate & non-device. nD will be missing if this is an
'All' level analysis.
List of all keys from deviceevents constituting
nA.
Optional. Count of exposures applicable to nA. This counts at
the device and covariate levels but not at the event level. If a matching
device and/or covariate level is not found, then exposure will be
NA. The exception is an 'All' level analysis, which counts
exposures across all levels.
Optional. List of all exposure keys from exposure
applicable to nA.
The mds_ts class attributes are as follows:
Short description of the analysis.
The analysis definition of class mds_da.
Boolean of whether exposure counts are present.
Boolean of whether 2x2 contingency table counts are present (presumably for disproportionality analysis or 'DPA').
Optional. If dpa is TRUE, list
object containing labels for the DPA contingency table.
Optional. If analysis definition includes covariate level
or time in-vivo, data.frame object containing the relevant data.
list: Generate time series from a list
mds_das: Generate time series from a list of defined analyses
mds_da: Generate time series using defined analysis
de <- deviceevent(maude, "date_received", "device_name", "event_type") ex <- exposure(sales, "sales_month", "device_name", count="sales_volume") da <- define_analyses(de, "device_name", exposure=ex) # Time series on one analysis time_series(da, de, ex) # Time series on multiple analyses time_series(da[1:3], de, ex)de <- deviceevent(maude, "date_received", "device_name", "event_type") ex <- exposure(sales, "sales_month", "device_name", count="sales_volume") da <- define_analyses(de, "device_name", exposure=ex) # Time series on one analysis time_series(da, de, ex) # Time series on multiple analyses time_series(da[1:3], de, ex)