Introduction to IncidencePrevalence

To do a study of incidence and prevalence, the analytics functions from this package that you would interact with are

  1. generateDenominatorCohortSet() and generateTargetDenominatorCohortSet() - these function will identify a set of denominator populations from the database population as a whole, the former, or based on individuals in a target cohort, the latter

  2. estimatePointPrevalence() and estimatePeriodPrevalence() - these function will estimate point and period prevalence for outcomes among denominator populations

  3. estimateIncidence() - this function will estimate incidence rates for outcomes among denominator populations

Below, we show an example analysis to provide an broad overview of how this functionality provided by the IncidencePrevalence package can be used. More context and further examples for each of these functions are provided in later vignettes.

First, let’s load relevant libraries.

library(CDMConnector)
library(IncidencePrevalence)
library(dplyr)
library(tidyr)
library(ggplot2)

The IncidencePrevalence package works with data mapped to the OMOP CDM and we will first need to connect to a database, after which we can use the CDMConnector package to represent our mapped data as a single R object. This could like something like:

con <- DBI::dbConnect(RPostgres::Postgres(),
  dbname = Sys.getenv("CDM5_POSTGRESQL_DBNAME"),
  host = Sys.getenv("CDM5_POSTGRESQL_HOST"),
  user = Sys.getenv("CDM5_POSTGRESQL_USER"),
  password = Sys.getenv("CDM5_POSTGRESQL_PASSWORD")
)
cdm <- CDMConnector::cdm_from_con(con,
  cdm_schema = Sys.getenv("CDM5_POSTGRESQL_CDM_SCHEMA"),
  write_schema = Sys.getenv("CDM5_POSTGRESQL_WRITE_SCHEMA")
)

For this example though we´ll generate 50,000 hypothetical patients using the mockIncidencePrevalenceRef() function.

cdm <- mockIncidencePrevalenceRef(
  sampleSize = 5000,
  outPre = 0.2
)

This example data already includes an outcome cohort.

cdm$outcome

Once we have a connection to the database set-up, we can use the generateDenominatorCohortSet() to identify a denominator cohort to use later when calculating incidence and prevalence. In this case we identify three denominator cohorts one with males, one with females, and one with both males and females included. For each of these cohorts only those aged between 18 and 65 from 2008 to 2012, and who had 365 days of prior history available are included.

cdm <- generateDenominatorCohortSet(
  cdm = cdm,
  name = "denominator",
  cohortDateRange = c(as.Date("2008-01-01"), as.Date("2012-01-01")),
  ageGroup = list(c(18, 65)),
  sex = c("Male", "Female", "Both"),
  daysPriorObservation = 365
)

We can see that each of our denominator cohorts is in the format of an OMOP CDM cohort:

cdm$denominator %>%
  glimpse()
#> Rows: ??
#> Columns: 4
#> Database: DuckDB v0.9.2 [eburn@Windows 10 x64:R 4.2.1/:memory:]
#> $ cohort_definition_id <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1…
#> $ subject_id           <chr> "4", "9", "10", "14", "17", "25", "26", "29", "30…
#> $ cohort_start_date    <date> 2008-01-01, 2008-01-01, 2008-01-01, 2008-01-01, …
#> $ cohort_end_date      <date> 2012-01-01, 2012-01-01, 2012-01-01, 2012-01-01, …

We can also see the settings associated with each cohort:

cohortSet(cdm$denominator)
#> Warning: `cohortSet()` was deprecated in CDMConnector 1.3.
#> ℹ Please use `settings()` instead.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.
#> # A tibble: 3 × 9
#>   cohort_definition_id cohort_name        age_group sex   days_prior_observation
#>                  <int> <chr>              <chr>     <chr>                  <dbl>
#> 1                    1 denominator_cohor… 18 to 65  Male                     365
#> 2                    2 denominator_cohor… 18 to 65  Fema…                    365
#> 3                    3 denominator_cohor… 18 to 65  Both                     365
#> # ℹ 4 more variables: start_date <date>, end_date <date>,
#> #   target_cohort_definition_id <int>, target_cohort_name <lgl>

And we can also see the count for each cohort

cohortCount(cdm$denominator)
#> # A tibble: 3 × 3
#>   cohort_definition_id number_records number_subjects
#>                  <int>          <int>           <int>
#> 1                    1           1099            1099
#> 2                    2           1120            1120
#> 3                    3           2219            2219

Now that we have our denominator cohorts, and using the outcome cohort that was also generated by the mockIncidencePrevalenceRef() function, we can estimate prevalence for each using the estimatePointPrevalence() function. Here we calculate point prevalence on a yearly basis.

prev <- estimatePeriodPrevalence(
  cdm = cdm,
  denominatorTable = "denominator",
  outcomeTable = "outcome",
  interval = "quarters",
  minCellCount = 0
)

prev %>%
  glimpse()
#> Rows: 48
#> Columns: 29
#> $ analysis_id                             <chr> "1", "1", "1", "1", "1", "1", …
#> $ prevalence_start_date                   <date> 2008-01-01, 2008-04-01, 2008-…
#> $ prevalence_end_date                     <date> 2008-03-31, 2008-06-30, 2008-…
#> $ n_cases                                 <int> 0, 0, 0, 0, 0, 1, 2, 0, 0, 0, …
#> $ n_population                            <int> 1018, 1023, 1022, 1022, 1024, …
#> $ prevalence                              <dbl> 0.0000000000, 0.0000000000, 0.…
#> $ prevalence_95CI_lower                   <dbl> 0.000000e+00, -2.168404e-19, 0…
#> $ prevalence_95CI_upper                   <dbl> 0.003759349, 0.003741044, 0.00…
#> $ population_obscured                     <chr> "FALSE", "FALSE", "FALSE", "FA…
#> $ cases_obscured                          <chr> "FALSE", "FALSE", "FALSE", "FA…
#> $ result_obscured                         <chr> "FALSE", "FALSE", "FALSE", "FA…
#> $ outcome_cohort_id                       <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, …
#> $ outcome_cohort_name                     <chr> "cohort_1", "cohort_1", "cohor…
#> $ analysis_type                           <chr> "period", "period", "period", …
#> $ analysis_interval                       <chr> "quarters", "quarters", "quart…
#> $ analysis_complete_database_intervals    <lgl> TRUE, TRUE, TRUE, TRUE, TRUE, …
#> $ analysis_time_point                     <chr> "start", "start", "start", "st…
#> $ analysis_full_contribution              <lgl> FALSE, FALSE, FALSE, FALSE, FA…
#> $ analysis_min_cell_count                 <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, …
#> $ denominator_cohort_id                   <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, …
#> $ denominator_cohort_name                 <chr> "denominator_cohort_1", "denom…
#> $ denominator_age_group                   <chr> "18 to 65", "18 to 65", "18 to…
#> $ denominator_sex                         <chr> "Male", "Male", "Male", "Male"…
#> $ denominator_days_prior_observation      <dbl> 365, 365, 365, 365, 365, 365, …
#> $ denominator_start_date                  <date> 2008-01-01, 2008-01-01, 2008-…
#> $ denominator_end_date                    <date> 2012-01-01, 2012-01-01, 2012-…
#> $ denominator_target_cohort_definition_id <int> NA, NA, NA, NA, NA, NA, NA, NA…
#> $ denominator_target_cohort_name          <lgl> NA, NA, NA, NA, NA, NA, NA, NA…
#> $ cdm_name                                <chr> "mock", "mock", "mock", "mock"…

Similarly we can use the estimateIncidence() function to estimate incidence rates. Here we annual incidence rates, with 180 days used for outcome washout windows.

inc <- estimateIncidence(
  cdm = cdm,
  denominatorTable = "denominator",
  outcomeTable = "outcome",
  interval = c("Years"),
  outcomeWashout = 180
)

inc %>%
  glimpse()
#> Rows: 12
#> Columns: 29
#> $ analysis_id                             <chr> "1", "1", "1", "1", "2", "2", …
#> $ n_persons                               <int> 1033, 1041, 1024, 1006, 1059, …
#> $ person_days                             <dbl> 371667, 368717, 362576, 357039…
#> $ n_events                                <int> 0, NA, NA, NA, 0, NA, NA, NA, …
#> $ incidence_start_date                    <date> 2008-01-01, 2009-01-01, 2010-…
#> $ incidence_end_date                      <date> 2008-12-31, 2009-12-31, 2010-…
#> $ person_years                            <dbl> 1017.5688, 1009.4921, 992.6790…
#> $ incidence_100000_pys                    <dbl> 0.0000, NA, NA, NA, 0.0000, NA…
#> $ incidence_100000_pys_95CI_lower         <dbl> 0.00000, NA, NA, NA, 0.00000, …
#> $ incidence_100000_pys_95CI_upper         <dbl> 362.5189, NA, NA, NA, 354.0540…
#> $ cohort_obscured                         <chr> "FALSE", "FALSE", "FALSE", "FA…
#> $ result_obscured                         <chr> "FALSE", "TRUE", "TRUE", "TRUE…
#> $ outcome_cohort_id                       <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, …
#> $ outcome_cohort_name                     <chr> "cohort_1", "cohort_1", "cohor…
#> $ analysis_outcome_washout                <chr> "180", "180", "180", "180", "1…
#> $ analysis_repeated_events                <lgl> FALSE, FALSE, FALSE, FALSE, FA…
#> $ analysis_interval                       <chr> "years", "years", "years", "ye…
#> $ analysis_complete_database_intervals    <lgl> TRUE, TRUE, TRUE, TRUE, TRUE, …
#> $ denominator_cohort_id                   <int> 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, …
#> $ analysis_min_cell_count                 <dbl> 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, …
#> $ denominator_cohort_name                 <chr> "denominator_cohort_1", "denom…
#> $ denominator_age_group                   <chr> "18 to 65", "18 to 65", "18 to…
#> $ denominator_sex                         <chr> "Male", "Male", "Male", "Male"…
#> $ denominator_days_prior_observation      <dbl> 365, 365, 365, 365, 365, 365, …
#> $ denominator_start_date                  <date> 2008-01-01, 2008-01-01, 2008-…
#> $ denominator_end_date                    <date> 2012-01-01, 2012-01-01, 2012-…
#> $ denominator_target_cohort_definition_id <int> NA, NA, NA, NA, NA, NA, NA, NA…
#> $ denominator_target_cohort_name          <lgl> NA, NA, NA, NA, NA, NA, NA, NA…
#> $ cdm_name                                <chr> "mock", "mock", "mock", "mock"…