Package {syrona}

syrona: Stratified prevalence comparison across OMOP CDM datasets

Description

Derives stratified prevalence tables from the condition, procedure, and drug records in OMOP CDM databases, computes log2 prevalence ratios between paired datasets, and synthesizes them via random-effects meta-analysis at multiple aggregation levels (year, age group, sex).

Author(s)

Maintainer: Maarja Pajusalu maarja.pajusalu@ut.ee

Authors:

• Maarja Pajusalu maarja.pajusalu@ut.ee

See Also

Useful links:

• https://github.com/HealthInformaticsUT/Syrona

• Report bugs at https://github.com/HealthInformaticsUT/Syrona/issues

Build the SELECT SQL for care-site cohort generation.

Description

Build the SELECT SQL for care-site cohort generation.

Usage

.build_caresite_sql(
  care_site_id,
  cohort_id,
  cdm_schema,
  collapse_strategy,
  restrict_to_observation
)

Age decade clamping: all ages >= this value merge into a single "80+" group.

Description

Age decade clamping: all ages >= this value merge into a single "80+" group.

Usage

AGE_CLAMP_MAX

ATC vocabulary constants for chapter lookup.

Description

ATC vocabulary constants for chapter lookup.

Usage

ATC_CHAPTER_VOCAB

Anchor concept_ids for condition chapter assignment.

Description

Anchor concept_ids for condition chapter assignment.

Usage

CHAPTER_ROOTS

SNOMED relationship types to extract as condition attributes.

Description

SNOMED relationship types to extract as condition attributes.

Usage

CONDITION_RELATIONSHIPS

Drug attribute relationships (empty - RxNorm relationships are structural).

Description

Drug attribute relationships (empty - RxNorm relationships are structural).

Usage

DRUG_RELATIONSHIPS

Gender concept_id to label mapping.

Description

Gender concept_id to label mapping.

Usage

GENDER_LABELS

k-anonymity threshold. Any stratum cell with fewer patients is suppressed.

Description

k-anonymity threshold. Any stratum cell with fewer patients is suppressed.

Usage

K_ANONYMITY

Anchor concept_ids for procedure chapter assignment.

Description

Anchor concept_ids for procedure chapter assignment.

Usage

PROCEDURE_CHAPTER_ROOTS

SNOMED relationship types to extract as procedure attributes.

Description

SNOMED relationship types to extract as procedure attributes.

Usage

PROCEDURE_RELATIONSHIPS

Base directory for extracted source data.

Description

Base directory for extracted source data.

Usage

SOURCES_DIR

Add prevalence ratio columns (log2 + natural + inference) to a data frame.

Description

Expects columns: prevalence_d1, prevalence_d2, denominator_d1, denominator_d2.

Usage

add_pr_columns(df)

Arguments

Details

Formulas: log2_pr = log2(p2 / p1) SE(ln) = sqrt((1-p1)/(p1*n1) + (1-p2)/(p2*n2)) SE(log2)= SE(ln) / ln(2) CI = log2_pr +/- 1.96 x SE

Value

Data frame with PR columns appended.

Apply OHDSI cohort filtering to CDM table references.

Description

Modifies db$cdm table references to filter by a standard OHDSI cohort table. Filters person, observation_period, death, and event tables to cohort members and their cohort windows.

Usage

apply_cohort_filter(db, cohort_id, cohort_schema = NULL)

Arguments

Value

Modified db list with filtered CDM table references.

Apply k-anonymity suppression to all extracted source tables.

Description

Apply k-anonymity suppression to all extracted source tables.

Usage

apply_k_anonymity(tables, k = K_ANONYMITY)

Arguments

Value

Named list of tibbles with k-anonymity applied.

Build a per-year forest plot for a single concept

Description

Shows yearly points + CIs, meta-analysis diamond, and colored heatmap tile row. Faceted by sex x age group.

Usage

build_forest_detail(
  yearly_data,
  meta_data,
  concept_name,
  concept_code,
  name1,
  name2,
  scale_mode = "log2"
)

Arguments

Value

A girafe object.

Build an overview forest plot paired with the heatmap

Description

Compact forest showing Female, Male, Both meta PR for every concept. Concept y-axis ordering matches the heatmap.

Usage

build_forest_overview(
  meta_sex_df,
  meta_summary_df,
  concept_ids,
  concept_info,
  name1,
  name2,
  scale_mode = "log2",
  concept_order = NULL
)

Arguments

Value

A girafe object.

Build a compact F/M/Both forest plot for a single concept

Description

Build a compact F/M/Both forest plot for a single concept

Usage

build_forest_summary(
  meta_sex_data,
  meta_summary_data,
  concept_name,
  concept_code,
  name1,
  name2,
  scale_mode = "log2"
)

Arguments

Value

A girafe object.

Build an interactive heatmap of prevalence ratios

Description

Build an interactive heatmap of prevalence ratios

Usage

build_heatmap(
  data,
  name1,
  name2,
  scale_mode = "log2",
  concept_weights = NULL,
  concept_order = NULL
)

Arguments

Value

A girafe object.

Build a one-row tibble from run_meta output + aggregated source columns.

Description

Build a one-row tibble from run_meta output + aggregated source columns.

Usage

build_meta_row(meta_result, id_cols, g)

Arguments

Value

One-row tibble.

Build a dumbbell chart showing absolute prevalence values

Description

Complements the forest detail (relative -> absolute). Same facet structure: sex x age_group.

Usage

build_point_diff(yearly_data, concept_name, concept_code, name1, name2)

Arguments

Value

A girafe object.

Build a PR distribution histogram from meta_summary data

Description

Build a PR distribution histogram from meta_summary data

Usage

build_pr_distribution(
  data,
  d1_name,
  d2_name,
  scale_mode = "fold",
  fold_thresh = FOLD_THRESHOLD,
  domain_label = "conditions"
)

Arguments

Value

A ggplot object.

Build a faceted PR distribution - one small histogram per chapter

Description

Interactive (ggiraph): clicking a chapter facet returns its chapter_id.

Usage

build_pr_distribution_chapters(
  data,
  d1_name,
  d2_name,
  scale_mode = "fold",
  fold_thresh = FOLD_THRESHOLD,
  domain_label = "conditions"
)

Arguments

Value

A girafe object. Selection data_id = chapter_id (character).

Build an interactive population pyramid

Description

Build an interactive population pyramid

Usage

build_pyramid(demo_df, dataset_name)

Arguments

Value

A girafe object.

Get summary statistics for a cohort.

Description

Get summary statistics for a cohort.

Usage

cohort_summary(con, cohort_id, cohort_schema = NULL)

Arguments

Value

A tibble with n_entries, n_persons, min_start, max_end.

Run the full comparison pipeline for two datasets across available domains.

Description

Loads both datasets, runs the 4-step comparison for each domain present in both, and optionally saves to CSV.

Usage

compare_all(
  d1_name,
  d2_name,
  domains = c("conditions", "procedures", "drugs"),
  save = TRUE
)

Arguments

Value

Named list of domain results (invisible).

Examples

# Run the bundled demo (a curated 32-concept subset) end to end.
# Copy it to a writable folder first, since the installed copy is read-only.
base <- tempdir()
file.copy(system.file("extdata", "demo", package = "syrona"),
          base, recursive = TRUE)
dir <- file.path(base, "demo")
old <- options(syrona.data_dir = dir)
# One domain keeps the example quick; drop `domains` to compare all three.
res <- compare_all("demo_population", "demo_selected", domains = "conditions")
res$condition_meta_summary
options(old)
# Then explore interactively: run_app(data_dir = dir)

Run the full comparison pipeline for one domain.

Description

Run the full comparison pipeline for one domain.

Usage

compare_domain(d1, d2, prev_table, domain_label)

Arguments

Value

Named list of 4 tibbles, or NULL if no overlapping concepts.

Meta-analysis across years: one row per concept_id x sex x age_group.

Description

Meta-analysis across years: one row per concept_id x sex x age_group.

Usage

compare_meta_agegroups(yearly_df)

Arguments

Value

tibble with meta-analyzed rows.

Meta-analysis across age groups: one row per concept_id x sex.

Description

Meta-analysis across age groups: one row per concept_id x sex.

Usage

compare_meta_by_sex(meta_agegroups_df)

Arguments

Value

tibble with meta-analyzed rows.

Meta-analysis across sexes: one row per concept_id (sex = "Both").

Description

Meta-analysis across sexes: one row per concept_id (sex = "Both").

Usage

compare_meta_summary(meta_by_sex_df)

Arguments

Value

tibble with one summary row per concept.

Compare two datasets at the per-year stratum level.

Description

Matches on concept_id x year x sex x age_group (inner join). Only keeps strata where both datasets have prevalence > 0.

Usage

compare_yearly(d1, d2, prev_table = "condition_prevalence")

Arguments

Value

tibble with one row per matched stratum, full PR column set.

Create an OHDSI cohort from a care site.

Description

For each person who visited the specified care site, their cohort window runs from their first visit start date to their last visit end date at that site. Optionally clips to observation period overlap.

Usage

create_caresite_cohort(
  con,
  care_site_id,
  cohort_id,
  cohort_schema = NULL,
  cdm_schema,
  overwrite = FALSE,
  restrict_to_observation = TRUE,
  collapse_strategy = c("person_span", "visit_occurrence")
)

Arguments

Details

This uses server-side INSERT...SELECT for performance on large databases (avoids downloading + re-uploading patient-level data).

Value

Number of rows inserted (invisible).

Create an OHDSI-standard cohort table.

Description

Creates the 4-column cohort table if it does not already exist. Works with both DuckDB and PostgreSQL.

Usage

create_cohort_table(con, cohort_schema = NULL)

Arguments

Value

Invisible TRUE if created, FALSE if already existed.

Delete a cohort from the cohort table.

Description

Delete a cohort from the cohort table.

Usage

delete_cohort(con, cohort_id, cohort_schema = NULL)

Arguments

Value

Number of rows deleted (invisible).

Run the full source data extraction pipeline.

Description

Derives stratified prevalence tables from the records in an OMOP CDM database for one or more clinical domains. Applies k-anonymity suppression and optionally saves results to CSV.

Usage

extract_all(
  dataset_name,
  db,
  domains = c("conditions", "procedures", "drugs"),
  cohort_id = NULL,
  cohort_schema = NULL,
  save = TRUE
)

Arguments

Value

Named list of tibbles matching the Syrona schema (invisible).

Extract condition SNOMED attributes.

Description

Extract condition SNOMED attributes.

Usage

extract_condition_attributes(cdm, condition_ids)

Arguments

Value

tibble with columns: concept_id, relationship, target_concept_id, target_concept_name

Extract condition chapter and sub-chapter assignments.

Description

Extract condition chapter and sub-chapter assignments.

Usage

extract_condition_chapters(cdm, condition_ids)

Arguments

Value

tibble with columns: concept_id, chapter_type, chapter_id, chapter_name, chapter_level, parent_chapter_id

Extract condition concept metadata.

Description

Extract condition concept metadata.

Usage

extract_condition_info(cdm)

Arguments

Value

tibble with columns: concept_id, concept_name, concept_code, vocabulary_id, concept_class_id, n_patients_total, n_records_total

Extract condition prevalence (ACHILLES-404 numerator + 116 denominator).

Description

Extract condition prevalence (ACHILLES-404 numerator + 116 denominator).

Usage

extract_condition_prevalence(cdm, denom_df)

Arguments

Value

tibble with columns: concept_id, year, sex, age_group, patient_count, record_count, denominator, prevalence

Extract death counts by year x sex x age group (ACHILLES-504 pattern).

Description

Extract death counts by year x sex x age group (ACHILLES-504 pattern).

Usage

extract_death_counts(cdm, denom_df)

Arguments

Value

tibble with columns: year, sex, age_group, death_count, denominator, mortality_rate

Extract demographics (birth year x sex).

Description

Extract demographics (birth year x sex).

Usage

extract_demographics(cdm)

Arguments

Value

tibble with columns: sex, birth_year, patient_count

Extract the ACHILLES-116 denominator: persons observed per year x sex x age group.

Description

Extract the ACHILLES-116 denominator: persons observed per year x sex x age group.

Usage

extract_denominators(cdm)

Arguments

Value

tibble with columns: year, sex, age_group, denominator

Extract drug chapter assignments (ATC 1st level).

Description

Extract drug chapter assignments (ATC 1st level).

Usage

extract_drug_chapters(cdm, drug_ids)

Arguments

Value

tibble with same columns as extract_condition_chapters.

Extract drug (ingredient) concept metadata.

Description

Extract drug (ingredient) concept metadata.

Usage

extract_drug_info(cdm)

Arguments

Value

tibble with same columns as extract_condition_info.

Extract drug prevalence at the Ingredient level.

Description

Extract drug prevalence at the Ingredient level.

Usage

extract_drug_prevalence(cdm, denom_df)

Arguments

Value

tibble with same columns as extract_condition_prevalence.

Extract procedure SNOMED attributes.

Description

Extract procedure SNOMED attributes.

Usage

extract_procedure_attributes(cdm, procedure_ids)

Arguments

Value

tibble with same columns as extract_condition_attributes.

Extract procedure chapter and sub-chapter assignments.

Description

Extract procedure chapter and sub-chapter assignments.

Usage

extract_procedure_chapters(cdm, procedure_ids)

Arguments

Value

tibble with same columns as extract_condition_chapters.

Extract procedure concept metadata.

Description

Extract procedure concept metadata.

Usage

extract_procedure_info(cdm)

Arguments

Value

tibble with same columns as extract_condition_info.

Extract procedure prevalence.

Description

Extract procedure prevalence.

Usage

extract_procedure_prevalence(cdm, denom_df)

Arguments

Value

tibble with columns: concept_id, year, sex, age_group, patient_count, record_count, denominator, prevalence

Format a log2 prevalence ratio as a fold difference string

Description

Vectorized. For values < 1, shows reciprocal in parentheses.

Usage

format_fold(log2_val)

Arguments

Value

Character vector of formatted fold strings.

Format p-values in Nature style

Description

Vectorized. Shows < 0.001 for very small values.

Usage

format_pval(p)

Arguments

Value

Character vector of formatted p-value strings.

Insert a cohort from a local data frame.

Description

Uploads a data frame to the database via omopgenerics::insertTable and marks it as a cohort table with omopgenerics::newCohortTable. Use this when cohort membership has already been computed locally (e.g. from a CSV or programmatic cohort definition).

Usage

insert_cohort(cdm, cohort_df, name = "cohort")

Arguments

Details

Requires that the CDM connection was created with a writeSchema.

Value

Updated CDM reference with the cohort table attached.

List care sites with patient counts.

Description

Useful for identifying care_site_id values before creating cohorts.

Usage

list_care_sites(con, cdm_schema, min_patients = 100)

Arguments

Value

A tibble with care_site_id, care_site_name, n_patients.

List available comparisons.

Description

List available comparisons.

Usage

list_comparisons()

Value

Character vector of comparison directory names.

List all available datasets.

Description

List all available datasets.

Usage

list_datasets()

Value

Character vector of dataset names.

Load a previously saved comparison from CSV.

Description

Load a previously saved comparison from CSV.

Usage

load_comparison(d1_name, d2_name)

Arguments

Value

Named list of tibbles.

Load a previously saved dataset from CSV.

Description

Load a previously saved dataset from CSV.

Usage

load_dataset(dataset_name)

Arguments

Value

Named list of tibbles.

Examples

base <- tempdir()
file.copy(system.file("extdata", "demo", package = "syrona"), base, recursive = TRUE)
old <- options(syrona.data_dir = file.path(base, "demo"))
d <- load_dataset("demo_population")
names(d)
options(old)

Load all Syrona design tokens into the calling environment

Description

Makes color constants, thresholds, and other design tokens available as variables. Used by the Shiny dashboard's global.R.

Usage

load_syrona_theme(envir = parent.frame())

Arguments

Value

No return value, called for its side effect of assigning the design tokens as variables in envir.

Run the Syrona dashboard

Description

Launches the Shiny dashboard for exploring prevalence comparisons. The app looks for data/sources/ and data/comparisons/ relative to your current working directory. Run this from the directory that contains your data/ folder.

Usage

run_app(data_dir = getwd(), port = NULL, launch.browser = TRUE, ...)

Arguments

Value

No return value, called for its side effect of launching the Shiny dashboard.

Examples

# Copy the bundled demo, generate the comparison, then launch the dashboard.
if (interactive()) {
  base <- tempdir()
  file.copy(system.file("extdata", "demo", package = "syrona"), base, recursive = TRUE)
  dir <- file.path(base, "demo")
  old <- options(syrona.data_dir = dir)
  compare_all("demo_population", "demo_selected")
  run_app(data_dir = dir)
  options(old)
}

Run meta-analysis on a vector of log2 prevalence ratios.

Description

Strategy: 1. Single study: Pass-Through (return as-is) 2. Try random-effects with Paule-Mandel tau 3. If RE fails: try fixed-effect 4. If both fail: return NULL

Usage

run_meta(te, se_te, studlab)

Arguments

Value

Named list with log2_pr, se, ci_low, ci_high, z, p_value, meta_model_type, tau2, I2, Q, pval_Q, lower_predict, upper_predict. NULL if meta-analysis fails.

Save comparison tables to CSV.

Description

Save comparison tables to CSV.

Usage

save_comparison(tables, d1_name, d2_name)

Arguments

Save extracted tables to CSV.

Description

Save extracted tables to CSV.

Usage

save_dataset(tables, dataset_name, db_path = NA_character_)

Arguments

Apply k-anonymity suppression to a single domain's tables.

Description

Apply k-anonymity suppression to a single domain's tables.

Usage

suppress_domain(
  info,
  prevalence,
  chapters,
  attributes,
  domain_label = "concept",
  k = K_ANONYMITY
)

Arguments

Value

Named list: prevalence, info, chapters, attributes, rare.

Connect to a DuckDB OMOP CDM.

Description

Opens a DuckDB file and creates a CDMConnector reference. By default the connection is read-only; set read_only = FALSE if you need to write cohort tables or temp tables into the database.

Usage

syrona_connect(
  db_path,
  cdm_schema = "main",
  write_schema = cdm_schema,
  read_only = TRUE
)

Arguments

Value

A list with components:

con

DBI connection object.

cdm

CDMConnector CDM reference (cdm_reference).

Connect to a PostgreSQL OMOP CDM.

Description

For remote databases, typically accessed via SSH tunnel: ssh -L 5432:localhost:5432 user@server.

Usage

syrona_connect_pg(
  host = "localhost",
  port = 5432,
  dbname,
  user,
  password = NULL,
  cdm_schema = "public",
  write_schema = cdm_schema
)

Arguments

Value

Same structure as syrona_connect.

Disconnect from an OMOP CDM database.

Description

Disconnect from an OMOP CDM database.

Usage

syrona_disconnect(db)

Arguments

Value

No return value, called for its side effect of closing the database connection.

Truncate a concept name to a maximum number of characters

Description

Adds "..." if truncated.

Usage

truncate_name(name, max = CONCEPT_NAME_MAX)

Arguments

Value

Character vector of (possibly truncated) names.

Map population weight (%) to a hex color on a log-scale gradient

Description

Light gray for rare concepts, dark charcoal for common ones.

Usage

weight_color(pct)

Arguments

Value

Character vector of hex color strings.