deviceevent {mds}

MD-PMS Device Event Data Frame

Description

Converts a data frame into a MD-PMS Device Event data frame.

Usage

deviceevent(
  data_frame,
  time,
  device_hierarchy,
  event_hierarchy,
  key = NULL,
  covariates = NULL,
  descriptors = NULL,
  time_invivo = NULL
)

Arguments

data_frame

The input data frame requiring components specified in the remaining arguments.

time

Character name of date variable in data_frame corresponding to the event. Class must be Date, POSIXt, or character.

Example: "event_date"

device_hierarchy

Vector of character variable names representing the device hierarchy in data_frame. Vector ordering is lowest level first, most general level last. If more than 2 variables, see important note in Details.

Example: c("Version", "Device", "ProductLine")

event_hierarchy

Vector of character variable names representing the event hierarchy in data_frame. Vector ordering is most specific event category first, most broad event category last. If more than 2 variables, see important note in Details.

Example: c("Event Code", "Event Group")

key

Character name of (uniquely identifying) primary key variable in data_frame. Class must be character or numeric.

Example: "key_ID"

Default: NULL will create a key variable.

covariates

Vector of character variable names representing the desired covariates to retain, all of which must be of class numeric or factor. "_all_" includes all covariates, assumed to be remaining variables in data_frame not already specified in key, time, device_hierarchy, or event_hierarchy. Covariates must be numeric, categorical, or binary in nature.

Example: c("Reporter", "Operation Time", "Country")

Default: NULL includes no covariates.

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. "_all_" includes all remaining variables in data_frame not already specified in key, time, device_hierarchy, event_hierarchy, or covariates. Typical descriptors are free text or high-dimensional categoricals.

Example: c("Description", "Unique Device Identifier")

Default: NULL includes no descriptors.

time_invivo

Character name of numeric variable in data_frame representing the time in vivo of the device at the time of the event time. See details for more.

IMPORTANT: If a call to define_analyses() is planned, time_invivo must be in the time units specified collectively by its parameters date_level and date_level_n.

Example: "Implanted Months". A value of 45 in the variable data_frame$'Implanted Months' would indicate 45 units of time elapsed since the device was first in vivo. If date_level="months" and date_level_n=1, this will be interpreted by define_analyses() as 45 months.

Default: NULL indicates this variable will not be used.

Details

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.

Value

A standardized MD-PMS data frame of class mds_de. Rows are deduplicated. Attributes are as follows:

key

Original variable name for key

time

Original variable name for time

device_hierarchy

Vector of original variable names for device_hierarchy with converted variable names correspondingly named.

event_hierarchy

Vector of original variable names for event_hierarchy with converted variable names correspondingly named.

covariates

Vector of original variable names for covariates with converted variable names correspondingly named.

descriptors

Vector of original variable names for descriptors with converted variable names correspondingly named.

Examples

# 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_")