Data Concepts

Concept objects are used in ricu as a way to specify how a clinical concept, such as heart rate can be loaded from a data source and are mainly consumed by load_concepts(). Several functions are available for constructing concept (and related auxiliary) objects either from code or by parsing a JSON formatted concept dictionary using load_dictionary().

new_cncpt(
  name,
  items,
  description = name,
  omopid = NA_integer_,
  category = NA_character_,
  aggregate = NULL,
  ...,
  target = "ts_tbl",
  class = "num_cncpt"
)

is_cncpt(x)

init_cncpt(x, ...)

# S3 method for num_cncpt
init_cncpt(x, unit = NULL, min = NULL, max = NULL, ...)

# S3 method for unt_cncpt
init_cncpt(x, unit = NULL, min = NULL, max = NULL, ...)

# S3 method for fct_cncpt
init_cncpt(x, levels, ...)

# S3 method for cncpt
init_cncpt(x, ...)

# S3 method for rec_cncpt
init_cncpt(
  x,
  callback = paste0("rename_data_var('", x[["name"]], "')"),
  interval = NULL,
  ...
)

new_concept(x)

concept(...)

is_concept(x)

as_concept(x)

Arguments

name

The name of the concept

items

Zero or more itm objects

description

String-valued concept description

omopid

OMOP identifier

category

String-valued category

aggregate

NULL or a string denoting a function used to aggregate per id and if applicable per time step

...

Further specification of the cncpt object (passed to init_cncpt())

target

The target object yielded by loading

class

NULL or a string-valued sub-class name used for customizing concept behavior

x

Object to query/dispatch on

unit

A string, specifying the measurement unit of the concept (can be NULL)

min, max

Scalar valued; defines a range of plausible values for a numeric concept

levels

A vector of possible values a categorical concept may take on

callback

Name of a function to be called on the returned data used for data cleanup operations

interval

Time interval used for data loading; if NULL, the respective interval passed as argument to load_concepts() is taken

Value

Constructors and coercion functions return cncpt and concept

objects, while inheritance tester functions return logical flags.

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 cncpt objects with a container class concept is motivated by the requirement of having several different sub-types of cncpt objects (all inheriting from the parent type cncpt), 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.

Each individual cncpt object contains the following information: a string- valued name, an item vector containing itm objects, a string-valued description (can be missing), a string-valued category designation (can be missing), a character vector-valued specification for an aggregation function and a target class specification (e.g. id_tbl or ts_tbl). Additionally, a sub- class to cncpt has to be specified, each representing a different data-scenario and holding further class-specific information. The following sub-classes to cncpt are available:

  • num_cncpt: The most widely used concept type is indented for concepts representing numerical measurements. Additional information that can be specified includes a string-valued unit specification, alongside a plausible range which can be used during data loading.

  • fct_cncpt: In case of categorical concepts, such as sex, a set of factor levels can be specified, against which the loaded data is checked.

  • lgl_cncpt: A special case of fct_cncpt, this allows only for logical values (TRUE, FALSE and NA).

  • rec_cncpt: More involved concepts, such as a SOFA score can pull in other concepts. Recursive concepts can build on other recursive concepts up to arbitrary recursion depth. Owing to the more complicated nature of such concepts, a callback function can be specified which is used in data loading for concept-specific post- processing steps.

  • unt_cncpt: A recent (experimental) addition which inherits from num_cncpt but instead of manual unit conversion, leverages

Class instantiation is organized in the same fashion as for item objects: concept() maps vector-valued arguments to new_cncpt(), which internally calls the S3 generic function init_cncpt(), while new_concept() instantiates a concept object from a list of cncpt objects (created by calls to new_cncpt()). Coercion is only possible from list and cncpt, by calling as_concept() and inheritance can be checked using is_concept() or is_cncpt().

Examples

if (require(mimic.demo)) {
gluc <- concept("glu",
  item("mimic_demo", "labevents", "itemid", list(c(50809L, 50931L))),
  description = "glucose", category = "chemistry",
  unit = "mg/dL", min = 0, max = 1000
)

is_concept(gluc)

identical(gluc, load_dictionary("mimic_demo", "glu"))

gl1 <- new_cncpt("glu",
  item("mimic_demo", "labevents", "itemid", list(c(50809L, 50931L))),
  description = "glucose"
)

is_cncpt(gl1)
is_concept(gl1)

conc <- concept(c("glu", "lact"),
  list(
    item("mimic_demo", "labevents", "itemid", list(c(50809L, 50931L))),
    item("mimic_demo", "labevents", "itemid", 50813L)
  ),
  description = c("glucose", "lactate")
)

conc

identical(as_concept(gl1), conc[1L])
}
#> [1] FALSE