new_itm {ricu}

Data items

Description

Item 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().

Usage

new_itm(src, ..., interval = NULL, target = NA_character_, class = "sel_itm")

is_itm(x)

init_itm(x, ...)

## S3 method for class 'sel_itm'
init_itm(x, table, sub_var, ids, callback = "identity_callback", ...)

## S3 method for class 'hrd_itm'
init_itm(x, table, sub_var, ids, callback = "identity_callback", ...)

## S3 method for class 'col_itm'
init_itm(x, table, unit_val = NULL, callback = "identity_callback", ...)

## S3 method for class 'rgx_itm'
init_itm(x, table, sub_var, regex, callback = "identity_callback", ...)

## S3 method for class 'fun_itm'
init_itm(x, callback, ...)

## S3 method for class 'itm'
init_itm(x, ...)

new_item(x)

item(...)

as_item(x)

is_item(x)

Arguments

src

The data source name

...

Further specification of the itm object (passed to init_itm())

interval

A default data loading interval (either specified as scalar difftime or string such as "00:01:00")

target

Item target class (e.g. "id_tbl"), NA indicates no specific class requirement

class

Sub class for customizing itm behavior

x

Object to query/dispatch on

table

Name of the table containing the data

sub_var

Column name used for subsetting

ids

Vector of ids used to subset table rows. If NULL, all rows are considered corresponding to the data item

callback

Name of a function to be called on the returned data used for data cleanup operations (or a string that evaluates to a function)

unit_val

String valued unit to be used in case no unit_var is available for the given table

regex

String-valued regular expression which will be evaluated by base::grepl() with ignore.case = TRUE

Details

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 220045⁠are looked up in the⁠itemid⁠column of⁠chartevents'.

• 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).

Value

Constructors and coercion functions return itm and item objects, while inheritance tester functions return logical flags.

Examples

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)))
}