ricu (version 0.5.6)

new_cncpt: Data Concepts

Description

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

Usage

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)

Value

Constructors and coercion functions return cncpt and concept

objects, while inheritance tester functions return logical flags.

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

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