Package {CohortUtilisation}

Title: Healthcare Resource Utilization on OMOP CDM Cohorts
Version: 0.6.1
Description: In-database healthcare resource utilization (HCRU) extraction across inpatient, emergency, outpatient, pharmacy, and procedure domains for Observational Medical Outcomes Partnership (OMOP) Common Data Model (CDM) cohorts following DARWIN EU standards.
License: MIT + file LICENSE
Copyright: IOMED, S.L.
URL: https://www.iomed.health/, https://github.com/iomedhealth/omopHeor
BugReports: https://github.com/iomedhealth/omopHeor/issues
Depends: R (≥ 4.1.0)
Imports: CDMConnector (≥ 1.4.0), omopgenerics (≥ 0.3.0), dbplyr (≥ 2.4.0), dplyr (≥ 1.1.0), ggplot2, rlang, cli, glue
Suggests: DBI, tibble, gt, PatientProfiles (≥ 1.2.0), CohortConstructor (≥ 0.2.0), CohortCharacteristics (≥ 0.3.0), visOmopResults, duckdb, testthat (≥ 3.0.0), withr
Config/testthat/edition: 3
Config/roxygen2/version: 8.1.0
Encoding: UTF-8
NeedsCompilation: no
Packaged: 2026-08-21 11:20:14 UTC; gabriel.maeztu
Author: Gabriel Maeztu [aut, cre]
Maintainer: Gabriel Maeztu <gabriel@iomed.health>
Repository: CRAN
Date/Publication: 2026-08-30 09:00:02 UTC

CohortUtilisation: Healthcare Resource Utilization on OMOP CDM Cohorts

Description

In-database healthcare resource utilization (HCRU) extraction across inpatient, emergency, outpatient, pharmacy, and procedure domains for Observational Medical Outcomes Partnership (OMOP) Common Data Model (CDM) cohorts following DARWIN EU standards.

Author(s)

Maintainer: Gabriel Maeztu gabriel@iomed.health

Authors:

See Also

Useful links:

Add Emergency Care Utilization Metrics to a Cohort

Description

Identifies emergency encounters by querying visit_occurrence and provider tables, capturing encounters with emergency visit concept IDs (e.g. 9203, 262, 581478) as well as visits delivered by emergency medicine specialist providers (e.g. 38004510), with optional granular specialty stratification.

Usage

addEmergencyCare(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  emergencyVisitConceptIds = c(9203L, 262L, 581478L),
  emergencySpecialtyConceptIds = c(38004510L),
  stratifySpecialty = FALSE,
  specialties = NULL,
  nameStyle = "emergency_visits_{window_name}",
  name = NULL
)

addEmergency(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  emergencyVisitConceptIds = c(9203L, 262L, 581478L),
  emergencySpecialtyConceptIds = c(38004510L),
  stratifySpecialty = FALSE,
  specialties = NULL,
  nameStyle = "emergency_visits_{window_name}",
  name = NULL
)

addEmergencyVisits(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  emergencyVisitConceptIds = c(9203L, 262L, 581478L),
  emergencySpecialtyConceptIds = c(38004510L),
  stratifySpecialty = FALSE,
  specialties = NULL,
  nameStyle = "emergency_visits_{window_name}",
  name = NULL
)

Arguments

x

A cohort table or cdm_table.

indexDate

Date variable in x anchoring the observation window. Default: "cohort_start_date".

censorDate

Optional date variable in x to censor observation.

window

A named or unnamed list of 2-element numeric vectors. Default: list(c(-365, -1), c(0, 365)).

emergencyVisitConceptIds

OMOP visit concept IDs for emergency care. Default: c(9203L, 262L, 581478L).

emergencySpecialtyConceptIds

OMOP provider specialty concept IDs for emergency medicine. Default: c(38004510L).

stratifySpecialty

Logical; whether to compute specialty breakdown. Default: FALSE.

specialties

Optional named list of integer vectors of OMOP specialty concept IDs for granular specialty breakdown. Default: NULL.

nameStyle

Column naming pattern. Default: "emergency_visits_{window_name}".

name

Name of the new table in the write schema. If NULL, a temporary table is returned.

Value

The cohort table x with added emergency visit metric columns.

Add Inpatient and ICU Hospitalization Metrics to a Cohort

Description

Add Inpatient and ICU Hospitalization Metrics to a Cohort

Usage

addInpatients(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  visitConceptIds = c(9201L, 8717L, 581379L),
  icuConceptIds = 32037L,
  icuSpecialtyConceptIds = c(38004500L),
  stratifySpecialty = FALSE,
  specialties = NULL,
  readmissions = FALSE,
  nameStyle = "{domain}_{metric}_{window_name}",
  name = NULL
)

addHospitalizations(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  visitConceptIds = c(9201L, 8717L, 581379L),
  icuConceptIds = 32037L,
  icuSpecialtyConceptIds = c(38004500L),
  stratifySpecialty = FALSE,
  specialties = NULL,
  readmissions = FALSE,
  nameStyle = "{domain}_{metric}_{window_name}",
  name = NULL
)

addInpatient(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  visitConceptIds = c(9201L, 8717L, 581379L),
  icuConceptIds = 32037L,
  icuSpecialtyConceptIds = c(38004500L),
  stratifySpecialty = FALSE,
  specialties = NULL,
  readmissions = FALSE,
  nameStyle = "{domain}_{metric}_{window_name}",
  name = NULL
)

Arguments

x

A cohort table or cdm_table.

indexDate

Date variable in x anchoring the observation window. Default: "cohort_start_date".

censorDate

Optional date variable in x to censor observation.

window

A named or unnamed list of 2-element numeric vectors. Default: list(c(-365, -1), c(0, 365)).

visitConceptIds

OMOP visit concept IDs for general inpatient stays. Default: c(9201L, 8717L, 581379L).

icuConceptIds

OMOP visit concept IDs for ICU stays. Default: 32037L.

icuSpecialtyConceptIds

OMOP provider specialty concept IDs for ICU stays. Default: c(38004500L).

stratifySpecialty

Logical; whether to compute specialty breakdown. Default: FALSE.

specialties

Optional named list of integer vectors of OMOP specialty concept IDs for granular specialty breakdown. Default: NULL.

readmissions

Logical; whether to compute 30-day and 90-day readmissions. Default: FALSE.

nameStyle

Column naming pattern. Default: "{domain}_{metric}_{window_name}".

name

Name of the new table in the write schema. If NULL, a temporary table is returned.

Value

The cohort table x with added inpatient metric columns.

Add Outpatient and Emergency Visits to a Cohort

Description

Add Outpatient and Emergency Visits to a Cohort

Usage

addOutpatientVisits(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  stratifySpecialty = TRUE,
  gpSpecialtyConceptIds = c(38004446L),
  specialties = NULL,
  includeEmergency = TRUE,
  nameStyle = "{setting}_visits_{window_name}",
  name = NULL
)

Arguments

x

A cohort table or cdm_table.

indexDate

Date variable in x anchoring the observation window. Default: "cohort_start_date".

censorDate

Optional date variable in x to censor observation.

window

A named or unnamed list of 2-element numeric vectors. Default: list(c(-365, -1), c(0, 365)).

stratifySpecialty

Logical; whether to partition visits by GP vs Specialist vs ED. Default: TRUE.

gpSpecialtyConceptIds

OMOP provider specialty concept IDs for General Practice. Default: c(38004446L).

specialties

Optional named list of integer vectors of OMOP specialty concept IDs for granular specialty breakdown. Default: NULL.

includeEmergency

Logical; whether to include emergency visits. Default: TRUE.

nameStyle

Column naming pattern. Default: "{setting}_visits_{window_name}".

name

Name of the new table in the write schema. If NULL, a temporary table is returned.

Value

The cohort table x with added outpatient visit metric columns.

Add Prescription and Medication Metrics to a Cohort

Description

Add Prescription and Medication Metrics to a Cohort

Usage

addPrescriptions(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  conceptSet = NULL,
  infusionRouteConceptIds = c(4171047L, 4171048L),
  daysSupply = TRUE,
  pdc = FALSE,
  nameStyle = "{metric}_{window_name}",
  name = NULL
)

Arguments

x

A cohort table or cdm_table.

indexDate

Date variable in x anchoring the observation window. Default: "cohort_start_date".

censorDate

Optional date variable in x to censor observation.

window

A named or unnamed list of 2-element numeric vectors. Default: list(c(-365, -1), c(0, 365)).

conceptSet

Optional concept set / codelist of specific drugs.

infusionRouteConceptIds

OMOP route concept IDs for parenteral/IV infusions. Default: c(4171047L, 4171048L).

daysSupply

Logical; whether to compute cumulative days supply. Default: TRUE.

pdc

Logical; whether to compute Proportion of Days Covered. Default: FALSE.

nameStyle

Column naming pattern. Default: "{metric}_{window_name}".

name

Name of the new table in the write schema. If NULL, a temporary table is returned.

Value

The cohort table x with added prescription metric columns.

Add Diagnostic Measurements and Procedure Occurrences to a Cohort

Description

Add Diagnostic Measurements and Procedure Occurrences to a Cohort

Usage

addProcedures(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  labConceptSet = NULL,
  imagingConceptSet = NULL,
  procedureConceptSet = NULL,
  nameStyle = "{metric}_count_{window_name}",
  name = NULL
)

Arguments

x

A cohort table or cdm_table.

indexDate

Date variable in x anchoring the observation window. Default: "cohort_start_date".

censorDate

Optional date variable in x to censor observation.

window

A named or unnamed list of 2-element numeric vectors. Default: list(c(-365, -1), c(0, 365)).

labConceptSet

Optional concept set / codelist for laboratory tests in measurement.

imagingConceptSet

Optional concept set / codelist for imaging scans in procedure_occurrence.

procedureConceptSet

Optional concept set / codelist for procedures in procedure_occurrence.

nameStyle

Column naming pattern. Default: "{metric}_count_{window_name}".

name

Name of the new table in the write schema. If NULL, a temporary table is returned.

Value

The cohort table x with added procedure and diagnostic metric columns.

Add Multi-Setting Visit Utilization Metrics to a Cohort

Description

Enriches an OMOP cohort table with Healthcare Resource Utilization (HCRU) metrics across Inpatient, Outpatient, and Emergency care settings in a single unified execution, with full support for provider specialty stratification across domains.

Usage

addVisits(
  x,
  indexDate = "cohort_start_date",
  censorDate = NULL,
  window = list(c(-365, -1), c(0, 365)),
  settings = c("inpatient", "outpatient", "emergency"),
  stratifySpecialty = TRUE,
  gpSpecialtyConceptIds = c(38004446L),
  icuSpecialtyConceptIds = c(38004500L),
  emergencySpecialtyConceptIds = c(38004510L),
  specialties = NULL,
  inpatientVisitConceptIds = c(9201L, 8717L, 581379L),
  outpatientVisitConceptIds = c(9202L, 581477L),
  emergencyVisitConceptIds = c(9203L, 262L, 581478L),
  icuConceptIds = 32037L,
  readmissions = FALSE,
  name = NULL
)

Arguments

x

A cohort table or cdm_table.

indexDate

Date variable in x anchoring the observation window. Default: "cohort_start_date".

censorDate

Optional date variable in x to censor observation.

window

A named or unnamed list of 2-element numeric vectors. Default: list(c(-365, -1), c(0, 365)).

settings

Character vector of care settings to extract. Allowed values: "inpatient", "outpatient", "emergency". Default: c("inpatient", "outpatient", "emergency").

stratifySpecialty

Logical; whether to partition visits by specialty. Default: TRUE.

gpSpecialtyConceptIds

OMOP provider specialty concept IDs for General Practice. Default: c(38004446L).

icuSpecialtyConceptIds

OMOP provider specialty concept IDs for ICU stays. Default: c(38004500L).

emergencySpecialtyConceptIds

OMOP provider specialty concept IDs for Emergency Medicine. Default: c(38004510L).

specialties

Optional named list of integer vectors of OMOP specialty concept IDs for granular specialty breakdown. Default: NULL.

inpatientVisitConceptIds

OMOP visit concept IDs for inpatient stays. Default: c(9201L, 8717L, 581379L).

outpatientVisitConceptIds

OMOP visit concept IDs for outpatient care. Default: c(9202L, 581477L).

emergencyVisitConceptIds

OMOP visit concept IDs for emergency care. Default: c(9203L, 262L, 581478L).

icuConceptIds

OMOP visit concept IDs for ICU stays. Default: 32037L.

readmissions

Logical; whether to compute 30-day and 90-day readmissions for inpatient stays. Default: FALSE.

name

Name of the new table in the write schema. If NULL, a temporary table is returned.

Value

The cohort table x with added multi-setting visit metric columns.

Create Infusion Administration Episode Cohorts

Description

Create Infusion Administration Episode Cohorts

Usage

computeInfusionCohorts(
  cdm,
  name,
  conceptSet = NULL,
  routeConceptIds = c(4171047L, 4171048L),
  collapseGap = 0L
)

Arguments

cdm

A cdm_reference object.

name

String specifying the cohort table name in the write schema.

conceptSet

Optional concept set / codelist of specific infused drugs.

routeConceptIds

Integer vector of OMOP route concept IDs. Default: c(4171047L, 4171048L).

collapseGap

Maximum gap in days between contiguous administration records to collapse. Default: 0L.

Value

An omopgenerics::cohort_table object.

Generate Hospitalization and Readmission Cohorts (Stage 1 & 2)

Description

Extracts inpatient visits from visit_occurrence, collapses contiguous or overlapping stays into discrete hospitalization episodes, and derives readmission cohorts within a specified washout window.

Usage

compute_hospitalization_cohorts(
  cdm,
  name,
  visit_concept_ids = c(9201L, 262L, 32037L, 581379L),
  readmission_window = 30L
)

computeHospitalizationCohorts(
  cdm,
  name,
  visitConceptIds = c(9201L, 262L, 581379L),
  icuConceptIds = 32037L,
  readmissionWindow = 30L,
  readmission_window = NULL
)

Arguments

cdm

A cdm_reference object.

name

String specifying the cohort table name in the write schema.

visit_concept_ids

Integer vector of OMOP visit concept IDs. Default: c(9201L, 262L, 32037L, 581379L).

readmission_window

Backward compatible snake_case parameter.

visitConceptIds

Integer vector of OMOP visit concept IDs. Default: c(9201L, 262L, 581379L).

icuConceptIds

Integer vector of OMOP ICU visit concept IDs. Default: 32037L.

readmissionWindow

Maximum days between previous discharge and next admission. Default: 30.

Value

An omopgenerics cohort table with cohort definitions:

Plot Summarised Healthcare Resource Utilization

Description

Plot Summarised Healthcare Resource Utilization

Usage

plotUtilization(result, metric = "inpatient_admissions", plotType = "barplot")

Arguments

result

A summarised_result object from summariseUtilization().

metric

Column or metric name pattern to plot. Default: "inpatient_admissions".

plotType

Visualization type: "barplot" or "boxplot". Default: "barplot".

Value

A ggplot2 visualization object.

Summarise Healthcare Resource Utilization for a Cohort

Description

Summarise Healthcare Resource Utilization for a Cohort

Usage

summariseUtilization(
  cohort,
  group = list("cohort_name"),
  strata = list(),
  estimates = c("mean", "sd", "median", "q25", "q75", "min", "max"),
  variables = NULL
)

Arguments

cohort

An enriched cohort table containing utilization columns.

group

List of character vectors specifying grouping columns. Default: list("cohort_name").

strata

List of character vectors specifying stratification columns. Default: list().

estimates

Summary estimators to compute. Default: c("mean", "sd", "median", "q25", "q75", "min", "max").

variables

Optional character vector of specific variables to summarise. If NULL, auto-detects utilization columns.

Value

An omopgenerics::summarised_result object.

Format Summarised Utilization as a Table

Description

Format Summarised Utilization as a Table

Usage

tableUtilization(
  result,
  type = "gt",
  header = c("cdm_name", "cohort_name"),
  estimateName = c(N = "<count>", `Mean (SD)` = "<mean> (<sd>)", `Median (IQR)` =
    "<median> (<q25> - <q75>)", `Min - Max` = "<min> - <max>"),
  ...
)

Arguments

result

A summarised_result object from summariseUtilization().

type

Output table format: "gt", "flextable", or "tibble". Default: "gt".

header

Character vector of columns to include in the header. Default: c("cdm_name", "cohort_name").

estimateName

Named character vector mapping estimate names.

...

Additional arguments passed to visOmopResults::visOmopTable().

Value

A formatted table object (gt_tbl, flextable, or tibble).