Package {rwevalidate}

Build the traffic-light validation summary table

Description

Collects each module's flags into one row per validation section, mapping to the regulatory framework the section addresses.

Usage

build_check_summary(results)

Arguments

Value

A data.frame with columns section, status, maps_to, detail.

Connect to an OMOP CDM database

Description

Opens a PostgreSQL connection via RPostgres and validates that the required clinical tables (person, observation_period, condition_occurrence, drug_exposure, measurement, visit_occurrence, death) exist in cdm_schema and the vocabulary tables (concept, concept_ancestor) exist in vocab_schema before returning. For split-schema CDMs (clinical and vocabulary in different schemas) pass vocab_schema; it defaults to cdm_schema for single-schema builds.

Usage

cdm_connect(
  host = "localhost",
  port = 5432,
  dbname,
  user,
  password,
  cdm_schema,
  vocab_schema = cdm_schema
)

Arguments

Value

A live DBI connection to the CDM database.

Examples

## Not run: 
# Requires a live PostgreSQL OMOP CDM server and real credentials, so this
# cannot be executed during checks. For a runnable, database-free demo of
# the package, see example_cdm() and validate_cohort().
con <- cdm_connect(
  dbname = "omop", user = "me", password = "secret",
  cdm_schema = "mimiciv_omop", vocab_schema = "vocab"
)
cdm_disconnect(con)

## End(Not run)

Disconnect from a CDM database

Description

Disconnect from a CDM database

Usage

cdm_disconnect(con)

Arguments

Value

Invisibly returns the result of DBI::dbDisconnect().

Examples

# Works on any DBI connection, demonstrated here on the bundled in-memory
# DuckDB example CDM (no database server needed).
if (requireNamespace("duckdb", quietly = TRUE)) {
  con <- example_cdm()
  cdm_disconnect(con)
}

Classify a vector of module flags into a traffic-light status

Description

Flags are strings prefixed "FAIL:" or "WARN:" (see the module functions). Any FAIL -> "fail" (red); else any WARN -> "warn" (amber); else "pass" (green).

Usage

classify_status(flags)

Arguments

Value

A single string: "pass", "warn", or "fail".

Create a small in-memory OMOP CDM for examples and demos

Description

Builds a tiny synthetic OMOP CDM (20 persons) in an in-memory DuckDB database and returns a live connection. Every table rwevalidate queries for the concept, attrition, density, and covariate modules is populated, together with a cohort table that has the standard subject_id, cohort_definition_id, cohort_start_date, and cohort_end_date columns. The cohort table carries two arms so all four modules can be demonstrated: persons 1-10 are the target cohort (cohort_definition_id = 1) and persons 11-20 are a comparator (cohort_definition_id = 2). The clinical tables and a minimal vocabulary both live in the default main schema.

Usage

example_cdm()

Details

This exists so the package can be tried, and its examples can run, without a live database connection. It is a synthetic demo fixture, not a substitute for a real CDM. The duckdb package (a soft dependency) must be installed. The caller owns the returned connection and should close it with cdm_disconnect().

Value

A live DBI connection to an in-memory DuckDB OMOP CDM.

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
  con <- example_cdm()
  attrition <- run_attrition(con, cdm_schema = "main",
                             cohort_table = "cohort", cohort_id = 1,
                             vocab_schema = "main")
  print(attrition$cohort_size)
  cdm_disconnect(con)
}

Render the validation report (HTML) and write the JSON sidecar

Description

Renders the bundled R Markdown template to a self-contained HTML report and writes a machine-readable validation_results.json alongside it.

Usage

render_validation_report(
  results,
  output_dir,
  cdm_schema,
  cohort_id,
  package_version = as.character(utils::packageVersion("rwevalidate")),
  run_date = Sys.time(),
  quiet = TRUE
)

Arguments

Value

Invisibly, a list with html, json, and check_summary.

Module 2 - Cohort Attrition Audit

Description

Profiles an instantiated cohort: size, index-date distribution, prior observation coverage, and demographics at index. Maps to HARPER section 5 and RECORD-PE item 6. All thresholds are arguments.

Usage

run_attrition(
  con,
  cdm_schema,
  cohort_table,
  cohort_id,
  obs_window = c(-365, 0),
  vocab_schema = "vocab",
  obs_warn_pct = 70,
  obs_fail_pct = 50,
  attrition_warn_threshold = 0.5
)

Arguments

Details

This profiles the cohort as it was handed in. It reports the cohort-level counts that item 6 asks for, but it does not yet rebuild a step-by-step attrition flowchart (how many subjects each inclusion or exclusion criterion removed), because the cohort table does not carry the criteria that built it. Per-criterion attrition is planned for a later version.

Value

A named list:

cohort_size

integer - distinct subjects in the cohort

index_date_summary

data.frame of index_year, n

obs_coverage

data.frame: cohort_n, n_sufficient, pct_sufficient, min_prior_days. cohort_n counts every cohort subject. A subject whose index date falls outside any observation period counts as insufficient prior observation rather than being dropped, so cohort_n matches cohort_size.

demographics

data.frame: sex, mean_age, min_age, max_age, n

flags

character vector of ⁠WARN:⁠/⁠FAIL:⁠ messages (empty if all pass)

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
  con <- example_cdm()
  res <- run_attrition(con, cdm_schema = "main", cohort_table = "cohort",
                       cohort_id = 1, vocab_schema = "main")
  res$cohort_size
  res$demographics
  cdm_disconnect(con)
}

Module 1 - Concept Coverage

Description

Profiles whether the cohort-defining concepts are present, well-mapped, and richly represented in the CDM. Maps to FDA RWE Relevance (are the data fit for the question?). This is the first module to read the vocabulary schema.

Usage

run_concepts(
  con,
  cdm_schema,
  cohort_table = NULL,
  cohort_id = NULL,
  concept_ids,
  domain = "condition",
  vocab_schema = "vocab",
  prevalence_warn_pct = 10,
  prevalence_fail_pct = 1,
  unmapped_warn_pct = 20
)

Arguments

Value

A named list:

prevalence

data.frame: n_with, n_total, pct

ancestor_coverage

data.frame: total_descendants, present_descendants, pct_present

mapping_by_domain

data.frame: domain, n_records, n_unmapped, pct_mapped

flags

character vector of ⁠WARN:⁠/⁠FAIL:⁠ messages

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
  con <- example_cdm()
  # 316139 = "Heart failure" (SNOMED), the seed concept in the demo CDM.
  res <- run_concepts(con, cdm_schema = "main", concept_ids = 316139,
                      domain = "condition", vocab_schema = "main")
  res$prevalence
  res$mapping_by_domain
  cdm_disconnect(con)
}

Module 4 - Covariate Feasibility

Description

Compares a target cohort against a comparator on baseline covariates: standardized mean differences (SMD love-plot data), a per-arm prevalence table, and a simple power calculation. Maps to HARPER Sec.4 (comparability). Runs only when a comparator_id is supplied.

Usage

run_covariates(
  con,
  cdm_schema,
  cohort_table,
  cohort_id,
  comparator_id,
  vocab_schema = "vocab",
  covariate_window = c(-365, 0),
  top_n = 20,
  smd_warn_threshold = 0.1,
  power_baseline_rate = 0.15,
  power_effect_rate = 0.3,
  power_sig_level = 0.05,
  power_warn_threshold = 0.8
)

Arguments

Value

A named list: smd_table, prevalence_table, power, flags.

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
  con <- example_cdm()
  # The demo CDM ships two arms: target = 1, comparator = 2.
  res <- run_covariates(con, cdm_schema = "main", cohort_table = "cohort",
                        cohort_id = 1, comparator_id = 2, vocab_schema = "main")
  res$smd_table
  res$power
  cdm_disconnect(con)
}

Module 3 - Temporal Data Density

Description

Profiles longitudinal data accrual around the index date: record density per patient per month across clinical domains, and follow-up completeness with a censoring-reason breakdown. Maps to FDA RWE Reliability (data accrual).

Usage

run_density(
  con,
  cdm_schema,
  cohort_table,
  cohort_id,
  obs_window = c(-365, 365),
  sparse_warn_min = 1
)

Arguments

Value

A named list:

density_by_domain

data.frame: domain, months_from_index, n_patients, n_records, records_per_patient

followup_summary

data.frame: one row per censoring_reason with n and median_followup_days (median over that group)

followup_detail

per-subject data.frame: subject_id, effective_end_date, followup_days, censoring_reason

flags

character vector of ⁠WARN:⁠/⁠FAIL:⁠ messages

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
  con <- example_cdm()
  res <- run_density(con, cdm_schema = "main", cohort_table = "cohort",
                     cohort_id = 1)
  head(res$density_by_domain)
  res$followup_summary
  cdm_disconnect(con)
}

Validate a patient cohort for real-world-evidence use

Description

One-call entry point: connects to the OMOP CDM (or uses a supplied connection), runs the attrition (Module 2) and temporal-density (Module 3) checks, and produces a self-contained HTML report plus a JSON sidecar aligned with FDA RWE and HARPER frameworks.

Usage

validate_cohort(
  cdm_schema,
  cohort_table,
  cohort_id = 1,
  con = NULL,
  vocab_schema = "vocab",
  concept_ids = NULL,
  concept_domain = "condition",
  comparator_id = NULL,
  obs_window = c(-365, 0),
  density_window = c(-365, 365),
  output_dir = "./validation_report",
  host = "localhost",
  port = 5432,
  dbname = NULL,
  user = NULL,
  password = NULL,
  render_html = TRUE,
  quiet = TRUE
)

Arguments

Details

Supply either an open con (e.g. for DuckDB testing) or PostgreSQL connection arguments (dbname, user, password, ...). Connections opened internally are closed on exit; a connection passed in via con is left open.

Against a live PostgreSQL OMOP CDM, a typical call looks like:

validate_cohort(
  cdm_schema   = "mimic_cdm",
  cohort_table = "results.rwevalidate_test_cohort",
  cohort_id    = 1,
  dbname = "FHIR", user = "me", password = "secret",
  vocab_schema = "vocab",
  output_dir   = "./validation_report"
)

Value

Invisibly, a list with results (module outputs + data_source), report (paths + check summary), and flags (all collected flags).

Examples

# Runnable demo on a small in-memory DuckDB CDM (no database needed).
# render_html = FALSE writes only the JSON sidecar, so Pandoc is not required.
if (requireNamespace("duckdb", quietly = TRUE)) {
  con <- example_cdm()
  out <- validate_cohort(
    cdm_schema   = "main",
    cohort_table = "cohort",
    cohort_id    = 1,
    con          = con,
    vocab_schema = "main",
    output_dir   = tempfile("rwe_demo_"),
    render_html  = FALSE
  )
  print(out$report$check_summary)
  cdm_disconnect(con)
}

Write the JSON sidecar (no rendering)

Description

Exposed separately so results can be persisted even when Pandoc is unavailable for HTML rendering.

Usage

write_results_json(
  results,
  output_dir,
  cdm_schema,
  cohort_id,
  package_version = as.character(utils::packageVersion("rwevalidate")),
  run_date = Sys.time(),
  check_summary = NULL
)

Arguments

Value

The path to the written JSON file (invisibly).