9  Function outputs

9.1 The summarised_result object

The summarised_result is the standard result format returned by all analytics functions in the ecosystem. It is an S3 class built on top of a tibble, defined in omopgenerics. Every package that produces estimates — prevalence, drug use, cohort characteristics, survival — returns a summarised_result. This standardisation is what allows visOmopResults and OmopViewer to work uniformly across the whole ecosystem without any package-specific code.

9.1.1 Structure

A summarised_result is a tibble with exactly 13 compulsory columns:

Column Type NA allowed Description
result_id integer No Groups rows sharing the same result settings.
cdm_name character No Name of the CDM instance used.
group_name character No Name side of the group name–level pair.
group_level character No Level side of the group name–level pair.
strata_name character No Name side of the strata name–level pair.
strata_level character No Level side of the strata name–level pair.
variable_name character No Name of the variable being estimated.
variable_level character Yes Sub-level of the variable (e.g. a category).
estimate_name character No Name of the estimate (snake_case).
estimate_type character No Type of the estimate value (see below).
estimate_value character No Value of the estimate, always stored as character.
additional_name character No Name side of the additional name–level pair.
additional_level character No Level side of the additional name–level pair.

The estimate_type column must be one of the values returned by omopgenerics::estimateTypeChoices(): "numeric", "integer", "date", "character", "proportion", "percentage", "logical".

9.1.1.1 Name–level pairs

Three pairs of columns — group_name/group_level, strata_name/strata_level, additional_name/additional_level — follow the same encoding. When a result applies to multiple dimensions simultaneously, the column names are concatenated with &&& and the values likewise:

group_name:  "cohort_name &&& sex"
group_level: "asthma_cohort &&& Female"
  • group: high-level identifiers, typically cohort name or codelist name.
  • strata: stratification dimensions such as age group or sex.
  • additional: any further dimensions that don’t fit in group or strata (e.g. time window, analysis type).

When a result is not stratified, these columns should contain "overall" / "overall".

9.1.2 Settings attribute

Every summarised_result has a settings attribute — a tibble with one row per result_id — that stores metadata about how the results were generated. Three settings columns are compulsory:

Setting Description
result_type A short snake_case string identifying the type of analysis (e.g. "summarised_characteristics"). Must be unique within a package.
package_name The name of the package that generated the result.
package_version The version of that package.

Additional settings columns store analysis-specific parameters (e.g. strata, ageGroup, window). A min_cell_count column is always present, defaulting to "0".

9.1.3 How to create a summarised_result

The standard pattern is to build a plain tibble with the 13 required columns, then convert it using omopgenerics::newSummarisedResult():

library(omopgenerics)

result <- tibble::tibble(
  result_id       = 1L,
  cdm_name        = cdmName(cdm),
  group_name      = "cohort_name",
  group_level     = "my_cohort",
  strata_name     = "overall",
  strata_level    = "overall",
  variable_name   = "age",
  variable_level  = NA_character_,
  estimate_name   = "mean",
  estimate_type   = "numeric",
  estimate_value  = as.character(mean_age),
  additional_name = "overall",
  additional_level= "overall"
) |>
  newSummarisedResult(
    settings = tibble::tibble(
      result_id       = 1L,
      result_type     = "my_result_type",
      package_name    = "myPackage",
      package_version = as.character(packageVersion("myPackage"))
    )
  )

In practice you will produce many rows at once. The recommended internal workflow is:

  1. Compute a tidy intermediate tibble (one row per subject / cohort / stratum / estimate).
  2. Use visOmopResults::uniteNameLevel() or omopgenerics helpers to encode name–level pairs.
  3. Call newSummarisedResult() with the appropriate settings.

9.1.4 Using the tidy format internally

The tidy() method converts a summarised_result back to a wide, human-readable format:

result |> tidy()

This is useful for inspecting results during development, and can also be used internally if your function needs to manipulate results before returning them. However, always return a summarised_result from exported functions — never a tidy tibble.

9.1.5 Suppression

If your function produces counts of patients or records, it must support cell suppression. The convention is to expose a minCellCount argument (default 5) and apply suppression before returning:

result <- result |> suppress(minCellCount = minCellCount)

suppress() replaces estimate values with NA where the count is below the threshold, and records the suppression threshold in the settings.

If your result contains a count of subjects (i.e. unique subject_id values), the estimate should be named count_subjects or n_subjects so that suppression is applied correctly.

9.1.6 One result_type per function

Each exported function that returns a summarised_result should produce exactly one result_type. Do not mix different analyses in a single summarised_result returned from one function — this makes it impossible for downstream tools to filter and process results by type.

9.1.7 Registering a result_type

Result types should be registered in your package so that visOmopResults and OmopViewer can discover them. Add a call to omopgenerics::registerResultType() in your package’s .onLoad() or document it in the package metadata. See the omopgenerics documentation for the current registration API.

9.2 Cohort outputs

Functions that return a modified cohort (rather than a summary) should return a cohort_table. The attrition log must be updated for every filtering step using recordCohortAttrition(). See Chapter 5 for the cohort_table class description.

9.3 Further reading