CohortPrevalenceExperiment R6 Class

Define and manage multi-dimensional prevalence analysis experiments. Enables users to specify cohorts, prevalence types, demographic constraints, and periods of interest, then automatically generates a Cartesian product of analysis definitions with full provenance tracking.

Details

The experiment class uses the builder pattern to define analysis dimensions:

1. Add cohorts (one or more)

2. Add prevalence types (one or more)

3. Add demographic constraints (one or more)

4. Add periods of interest (one or more)

5. Set common parameters (strata, output types)

6. Call define() to materialize analysis objects

7. Pass analysis list to generatePrevalence()

Design Philosophy

• Input: Object-based (type-safe), validated on each addition

• Output: Flat tibble specification, CSV-exportable for reproducibility

• Execution: exp$define() → generatePrevalence(analyses, ...)

  • Explicit data flow: experiment defines dimensions, define() materializes analyses, generatePrevalence() executes

Example

exp <- CohortPrevalenceExperiment$new("CKD Multi-Cohort")



exp$addCohorts(tibble::tibble(

  cohortId = c(1, 2, 3),

  cohortName = c("CKD A", "CKD B", "CKD C")

))



exp$addPrevalenceTypes(list(

  createPrevalenceType("point", lookBackDays = 0L),

  createPrevalenceType("period_prevalence_pd2", lookBackDays = 365L),

  createPrevalenceType("period_prevalence_pd3", lookBackDays = 0L)

))



exp$addDemographicConstraints(list(

  createDemographicConstraints(ageMin = 18, ageMax = 150, genderIds = c(8507L, 8532L, 0L)),

  createDemographicConstraints(ageMin = 65, ageMax = 150, genderIds = c(8507L, 8532L, 0L)),

  createDemographicConstraints(ageMin = 18, ageMax = 150, genderIds = c(8507L))

))



exp$addPeriodsOfInterest(list(

  createYearlyRange(2015:2024),

  createSpan(start = "2020-01-01", end = "2020-12-31"),

  createSpan(start = "2021-01-01", end = "2021-12-31")

))



exp$setCommonParameters(strata = c("age", "gender"), outputTypes = "prevalence")



# View specification

exp$viewDesign()

exp$viewDesign("html")



# Define analyses (3 × 3 × 3 × 3 = 81 analyses)

analyses <- exp$define()



# Execute

results <- generatePrevalence(analyses, executionSettings = settings)

Methods

Public methods

• CohortPrevalenceExperiment$new()

• CohortPrevalenceExperiment$addCohorts()

• CohortPrevalenceExperiment$addPrevalenceTypes()

• CohortPrevalenceExperiment$addDemographicConstraints()

• CohortPrevalenceExperiment$addPeriodsOfInterest()

• CohortPrevalenceExperiment$setCommonParameters()

• CohortPrevalenceExperiment$validate()

• CohortPrevalenceExperiment$getSpecification()

• CohortPrevalenceExperiment$viewDesign()

• CohortPrevalenceExperiment$define()

• CohortPrevalenceExperiment$clone()

---

Method new()

Create new experiment

Usage

CohortPrevalenceExperiment$new(name, description = NULL)

Arguments

name

Character. Descriptive name for the experiment

description

Character. Optional description

---

Method addCohorts()

Add cohort definitions

Usage

CohortPrevalenceExperiment$addCohorts(cohorts)

Arguments

cohorts

Tibble with columns:

• cohortId (numeric, required): cohort ID in the results schema

• cohortName (character, required): display name

Returns

Invisibly returns self for method chaining

---

Method addPrevalenceTypes()

Add prevalence type definitions

Usage

CohortPrevalenceExperiment$addPrevalenceTypes(types_list)

Arguments

types_list

List of prevalenceType objects (created via createPrevalenceType)

Returns

Invisibly returns self for method chaining

---

Method addDemographicConstraints()

Add demographic constraint definitions

Usage

CohortPrevalenceExperiment$addDemographicConstraints(constraints_list)

Arguments

constraints_list

List of demographicConstraints objects (created via createDemographicConstraints)

Returns

Invisibly returns self for method chaining

---

Method addPeriodsOfInterest()

Add periods of interest

Usage

CohortPrevalenceExperiment$addPeriodsOfInterest(poi_list)

Arguments

poi_list

List of period objects (YearlyRange or Span objects)

Returns

Invisibly returns self for method chaining

---

Method setCommonParameters()

Set common parameters for all analyses

Usage

CohortPrevalenceExperiment$setCommonParameters(
  strata = NULL,
  outputTypes = NULL,
  minimumObservationLength = 0L,
  useOnlyFirstObservationPeriod = FALSE
)

Arguments

strata

Character vector of strata variables (e.g., c("age", "gender"))

outputTypes

Character vector of output types (e.g., "prevalence")

minimumObservationLength

Integer minimum lead-in days before each POI start date

useOnlyFirstObservationPeriod

Logical. If TRUE, only first observation period per person is used

Returns

Invisibly returns self for method chaining

---

Method validate()

Validate all required parameters are set

Usage

CohortPrevalenceExperiment$validate()

Returns

Invisibly returns TRUE if valid, otherwise stops with error

---

Method getSpecification()

Get specification as flat tibble

Usage

CohortPrevalenceExperiment$getSpecification()

Returns

Tibble with one row per analysis combination

---

Method viewDesign()

View experiment design

Usage

CohortPrevalenceExperiment$viewDesign(format = "console")

Arguments

format

Character. "console" (default) for text table, "html" for interactive reactable

Returns

Invisibly returns specification tibble

---

Method define()

Define analysis specifications (create analysis objects)

Usage

CohortPrevalenceExperiment$define(autoIdStart = 1L)

Arguments

autoIdStart

Numeric. Starting ID for analyses (default: 1L)

Returns

List of CohortPrevalenceAnalysis objects with specification attached as attribute

---

Method clone()

The objects of this class are cloneable with this method.

Usage

CohortPrevalenceExperiment$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.