data_items.RdItem objects are used in ricu as a way to specify how individual data
items corresponding to clinical concepts (see also concept()), such as
heart rate can be loaded from a data source. Several functions are
available for constructing item (and related auxiliary) objects either
from code or by parsing a JSON formatted concept dictionary using
load_dictionary().
new_itm(src, ..., interval = NULL, target = NA_character_, class = "sel_itm")
is_itm(x)
init_itm(x, ...)
# S3 method for sel_itm
init_itm(x, table, sub_var, ids, callback = "identity_callback", ...)
# S3 method for hrd_itm
init_itm(x, table, sub_var, ids, callback = "identity_callback", ...)
# S3 method for col_itm
init_itm(x, table, unit_val = NULL, callback = "identity_callback", ...)
# S3 method for rgx_itm
init_itm(x, table, sub_var, regex, callback = "identity_callback", ...)
# S3 method for fun_itm
init_itm(x, callback, ...)
# S3 method for itm
init_itm(x, ...)
new_item(x)
item(...)
as_item(x)
is_item(x)The data source name
Further specification of the itm object (passed to
init_itm())
A default data loading interval (either specified as scalar
difftime or string such as "00:01:00")
Item target class (e.g. "id_tbl"), NA indicates no specific
class requirement
Sub class for customizing itm behavior
Object to query/dispatch on
Name of the table containing the data
Column name used for subsetting
Vector of ids used to subset table rows. If NULL, all rows are
considered corresponding to the data item
Name of a function to be called on the returned data used for data cleanup operations (or a string that evaluates to a function)
String valued unit to be used in case no unit_var is
available for the given table
String-valued regular expression which will be evaluated by
base::grepl() with ignore.case = TRUE
Constructors and coercion functions return itm and item objects,
while inheritance tester functions return logical flags.
In order to allow for a large degree of flexibility (and extensibility), which is much needed owing to considerable heterogeneity presented by different data sources, several nested S3 classes are involved in representing a concept. An outline of this hierarchy can be described as
concept: contains many cncpt objects (of potentially
differing sub-types), each comprising of some meta-data and an item
object
item: contains many itm objects (of potentially differing
sub-types), each encoding how to retrieve a data item.
The design choice for wrapping a vector of itm objects with a container
class item is motivated by the requirement of having several different
sub-types of itm objects (all inheriting from the parent type itm),
while retaining control over how this homogeneous w.r.t. parent type, but
heterogeneous w.r.t. sub-type vector of objects behaves in terms of S3
generic functions.
The following sub-classes to itm are available, each representing a
different data-scenario:
sel_itm: The most widely used item class is intended for the situation
where rows of interest can be identified by looking for occurrences of a
set of IDs (ids) in a column (sub_var). An example for this is heart
rate hr on mimic, where the IDs 211 and 220045are looked up in theitemidcolumn ofchartevents`.
col_itm: This item class can be used if no row-subsetting is required.
An example for this is heart rate (hr) on eicu, where the table
vitalperiodic contains an entire column dedicated to heart rate
measurements.
rgx_itm: As alternative to the value-matching approach of sel_itm
objects, this class identifies rows using regular expressions. Used for
example for insulin in eicu, where the regular expression ^insulin (250.+)?\\(((ml|units)/hr)?\\)$ is matched against the drugname column
of infusiondrug. The regular expression is evaluated by base::grepl()
with ignore.case = TRUE.
fun_itm: Intended for the scenario where data of interest is not
directly available from a table, this itm class offers most flexibility.
A function can be specified as callback and this function will be called
with arguments x (the object itself), patient_ids, id_type and
interval (see load_concepts()) and is expected to return an object as
specified by the target entry.
hrd_itm: A special case of sel_itm for HiRID data where measurement
units are not available as separate column, but as separate table with
units fixed per concept.
All itm objects have to specify a data source (src) as well as a
sub-class. Further arguments then are specific to the respective sub-class
and encode information that define data loading, such as the table to
query, the column name and values to use for identifying relevant rows,
etc. The S3 generic function init_itm() is responsible for input
validation of class-specific arguments as well as class initialization. A
list of itm objects, created by calls to new_itm() can be passed to
new_item in order to instantiate an item object. An alternative
constructor for item objects is given by item() which calls new_itm()
on the passed arguments (see examples). Finally as_item() can be used
for coercion of related objects such as list, concept, and the like.
Several additional S3 generic functions exist for manipulation of
item-like objects but are marked internal (see
item/concept utilities).
if (require(mimic.demo)) {
gluc <- item("mimic_demo", "labevents", "itemid", list(c(50809L, 50931L)),
unit_var = TRUE, target = "ts_tbl")
is_item(gluc)
all.equal(gluc, as_item(load_dictionary("mimic_demo", "glu")))
hr1 <- new_itm(src = "mimic_demo", table = "chartevents",
sub_var = "itemid", ids = c(211L, 220045L))
hr2 <- item(src = c("mimic_demo", "eicu_demo"),
table = c("chartevents", "vitalperiodic"),
sub_var = list("itemid", NULL),
val_var = list(NULL, "heartrate"),
ids = list(c(211L, 220045L), FALSE),
class = c("sel_itm", "col_itm"))
hr3 <- new_itm(src = "eicu_demo", table = "vitalperiodic",
val_var = "heartrate", class = "col_itm")
identical(as_item(hr1), hr2[1])
identical(new_item(list(hr1)), hr2[1])
identical(hr2, as_item(list(hr1, hr3)))
}
#> [1] TRUE