Title:	Build and Manipulate Study Cohorts Using a Common Data Model
Version:	0.6.0
Description:	Create and manipulate study cohorts in data mapped to the Observational Medical Outcomes Partnership Common Data Model.
License:	Apache License (≥ 2)
Encoding:	UTF-8
RoxygenNote:	7.3.3
Imports:	cli, clock, dplyr, glue, omopgenerics (≥ 1.3.2), PatientProfiles (≥ 1.4.4), purrr, rlang, tidyr, utils
Suggests:	CDMConnector (≥ 1.7.0), CirceR, CodelistGenerator (≥ 3.4.1), CohortCharacteristics, covr, DBI, DiagrammeR, DrugUtilisation, duckdb, ggplot2, ggpubr, gt, here, IncidencePrevalence, knitr, odbc, omock (≥ 0.5.0), rmarkdown, RPostgres, scales, SqlRender, stringr, testthat (≥ 3.0.0), tictoc, visOmopResults
Config/testthat/edition:	3
Config/testthat/parallel:	true
VignetteBuilder:	knitr
Depends:	R (≥ 4.1)
URL:	https://ohdsi.github.io/CohortConstructor/, https://github.com/OHDSI/CohortConstructor
LazyData:	true
NeedsCompilation:	no
Packaged:	2025-10-31 15:13:38 UTC; orms0426
Author:	Edward Burn [aut, cre], Martí Català [aut], Nuria Mercade-Besora [aut], Marta Alcalde-Herraiz [aut], Mike Du [aut], Yuchen Guo [aut], Xihang Chen [aut], Kim Lopez-Guell [aut], Elin Rowlands [aut]
Maintainer:	Edward Burn <edward.burn@ndorms.ox.ac.uk>
Repository:	CRAN
Date/Publication:	2025-10-31 15:50:02 UTC

CohortConstructor: Build and Manipulate Study Cohorts Using a Common Data Model

Description

Create and manipulate study cohorts in data mapped to the Observational Medical Outcomes Partnership Common Data Model.

Author(s)

Maintainer: Edward Burn edward.burn@ndorms.ox.ac.uk (ORCID)

Authors:

• Martí Català marti.catalasabate@ndorms.ox.ac.uk (ORCID)

• Nuria Mercade-Besora nuria.mercadebesora@ndorms.ox.ac.uk (ORCID)

• Marta Alcalde-Herraiz marta.alcaldeherraiz@ndorms.ox.ac.uk (ORCID)

• Mike Du mike.du@ndorms.ox.ac.uk (ORCID)

• Yuchen Guo yuchen.guo@ndorms.ox.ac.uk (ORCID)

• Xihang Chen xihang.chen@ndorms.ox.ac.uk (ORCID)

• Kim Lopez-Guell kim.lopez@spc.ox.ac.uk (ORCID)

• Elin Rowlands elin.rowlands@ndorms.ox.ac.uk (ORCID)

See Also

Useful links:

• https://ohdsi.github.io/CohortConstructor/

• https://github.com/OHDSI/CohortConstructor

Add an index to a cohort table

Description

Adds an index on subject_id and cohort_start_date to a cohort table. Note, currently only indexes will be added if the table is in a postgres database.

Usage

addCohortTableIndex(cohort)

Arguments

Value

The cohort table

Helper for consistent documentation of arguments in atFirst functions.

Description

Helper for consistent documentation of arguments in atFirst functions.

Arguments

Helper for consistent documentation of conceptCohort and measurementCohort.

Description

Helper for consistent documentation of conceptCohort and measurementCohort.

Arguments

Run benchmark of CohortConstructor package

Description

Run benchmark of CohortConstructor cohort instantiation time compared to CIRCE from JSON. More information in the benchmarking vignette.

Usage

benchmarkCohortConstructor(
  cdm,
  runCIRCE = TRUE,
  runCohortConstructorDefinition = TRUE,
  runCohortConstructorDomain = TRUE,
  dropCohorts = TRUE
)

Arguments

Benchmarking results

Description

Benchmarking results

Usage

benchmarkData

Format

A list of results from benchmarking

Helper for consistent documentation of cdm.

Description

Helper for consistent documentation of cdm.

Arguments

Helper for consistent documentation of cohort.

Description

Helper for consistent documentation of cohort.

Arguments

Helper for consistent documentation of cohortId.

Description

Helper for consistent documentation of cohortId.

Arguments

Helper for consistent documentation of cohortId.

Description

Helper for consistent documentation of cohortId.

Arguments

Collapse cohort entries using a certain gap to concatenate records.

Description

collapseCohorts() concatenates cohort records, allowing for some number of days between one finishing and the next starting.

Usage

collapseCohorts(
  cohort,
  cohortId = NULL,
  gap = 0,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

A cohort table

Helper for consistent documentation of collapse.

Description

Helper for consistent documentation of collapse.

Arguments

Helper for consistent documentation of dateColumns and returnReason.

Description

Helper for consistent documentation of dateColumns and returnReason.

Arguments

Create cohorts based on a concept set

Description

conceptCohort() creates a cohort table from patient records from the clinical tables in the OMOP CDM.

The following tables are currently supported for creating concept cohorts:

• condition_occurrence

• device_exposure

• drug_exposure

• measurement

• observation

• procedure_occurrence

• visit_occurrence

Cohort duration is based on record start and end (e.g. condition_start_date and condition_end_date for records coming from the condition_occurrence tables). So that the resulting table satisfies the requirements of an OMOP CDM cohort table:

• Cohort entries will not overlap. Overlapping records will be combined based on the overlap argument.

• Cohort entries will not go out of observation. If a record starts outside of an observation period it will be silently ignored. If a record ends outside of an observation period it will be trimmed so as to end at the preceding observation period end date.

Usage

conceptCohort(
  cdm,
  conceptSet,
  name,
  exit = "event_end_date",
  overlap = "merge",
  table = NULL,
  useRecordsBeforeObservation = FALSE,
  useSourceFields = FALSE,
  subsetCohort = NULL,
  subsetCohortId = NULL
)

Arguments

Value

A cohort table

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort <- conceptCohort(cdm = cdm, conceptSet = list(a = 444074), name = "cohort")

cdm$cohort |>
  attrition()

# Create a cohort based on a concept set. The cohort exit is set to the event start date.
# If two records overlap, the cohort end date is set as the sum of the duration of
# all overlapping records. Only individuals included in the existing `cohort` will be considered.

conceptSet <- list(
  "nitrogen" = c(35604434, 35604439),
  "potassium" = c(40741270, 42899580, 44081436)
)

cdm$study_cohort <- conceptCohort(cdm = cdm,
                                  conceptSet = conceptSet,
                                  name = "study_cohort",
                                  exit = "event_start_date",
                                  overlap = "extend",
                                  subsetCohort = "cohort")

cdm$study_cohort |>
  attrition()
}

Helper for consistent documentation of conceptSet.

Description

Helper for consistent documentation of conceptSet.

Arguments

Copy a cohort table

Description

copyCohorts() copies an existing cohort table to a new location.

Usage

copyCohorts(cohort, name, n = 1, cohortId = NULL)

Arguments

Value

A new cohort table containing cohorts from the original cohort table.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort3 <- copyCohorts(cdm$cohort1, n = 2, cohortId = 1, name = "cohort3")
}

Helper for consistent documentation of days.

Description

Helper for consistent documentation of days.

Arguments

Create cohort based on the death table

Description

Create cohort based on the death table

Usage

deathCohort(cdm, name, subsetCohort = NULL, subsetCohortId = NULL)

Arguments

Value

A cohort table with a death cohort in cdm

Examples

if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
library(CohortConstructor)

cdm <- mockCohortConstructor()

# Generate a death cohort
death_cohort <- deathCohort(cdm, name = "death_cohort")
death_cohort

# Create a death cohort for females aged over 50 years old.

# Create a demographics cohort with age range and sex filters
cdm$my_cohort <- demographicsCohort(cdm, "my_cohort", ageRange = c(50,100), sex = "Female")

# Generate a death cohort, restricted to individuals in 'my_cohort'
death_cohort <- deathCohort(cdm, name = "death_cohort", subsetCohort = "my_cohort")
death_cohort |> attrition()
}

Create cohorts based on patient demographics

Description

demographicsCohort() creates a cohort table based on patient characteristics. If and when an individual satisfies all the criteria they enter the cohort. When they stop satisfying any of the criteria their cohort entry ends.

Usage

demographicsCohort(
  cdm,
  name,
  ageRange = NULL,
  sex = NULL,
  minPriorObservation = NULL
)

Arguments

Value

A cohort table

Examples

if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
library(CohortConstructor)

cdm <- mockCohortConstructor()

cohort <-  cdm |>
    demographicsCohort(name = "cohort3", ageRange = c(18,40), sex = "Male")

attrition(cohort)

# Can also create multiple demographic cohorts, and add minimum prior history requirements.

cohort <- cdm |>
    demographicsCohort(name = "cohort4",
    ageRange = list(c(0, 19),c(20, 64),c(65, 150)),
    sex = c("Male", "Female", "Both"),
    minPriorObservation = 365)

attrition(cohort)
}

Update cohort start date to be the first date from of a set of column dates

Description

entryAtFirstDate() resets cohort start date based on a set of specified column dates. The first date that occurs is chosen.

Usage

entryAtFirstDate(
  cohort,
  dateColumns,
  cohortId = NULL,
  returnReason = FALSE,
  keepDateColumns = TRUE,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

The cohort table.

Examples

library(CohortConstructor)
library(PatientProfiles)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 <- cdm$cohort1 |>
  addTableIntersectDate(
    tableName = "drug_exposure",
    nameStyle = "prior_drug",
    order = "last",
    window = c(-Inf, 0)
  ) |>
  addPriorObservation(priorObservationType = "date", name = "cohort1")

cdm$cohort1 |>
  entryAtFirstDate(dateColumns = c("prior_drug", "prior_observation"))
}

Set cohort start date to the last of a set of column dates

Description

entryAtLastDate() resets cohort end date based on a set of specified column dates. The last date is chosen.

Usage

entryAtLastDate(
  cohort,
  dateColumns,
  cohortId = NULL,
  returnReason = FALSE,
  keepDateColumns = TRUE,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

The cohort table.

Examples

if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
library(CohortConstructor)
library(PatientProfiles)

cdm <- mockCohortConstructor()

cdm$cohort1 <- cdm$cohort1 |>
  addTableIntersectDate(
    tableName = "drug_exposure",
    nameStyle = "prior_drug",
    order = "last",
    window = c(-Inf, 0)
  ) |>
  addPriorObservation(priorObservationType = "date", name = "cohort1")

cdm$cohort1 |>
  entryAtLastDate(dateColumns = c("prior_drug", "prior_observation"))
}

Set cohort end date to death date

Description

This functions changes cohort end date to subject's death date. In the case were this generates overlapping records in the cohort, those overlapping entries will be merged.

Usage

exitAtDeath(
  cohort,
  cohortId = NULL,
  requireDeath = FALSE,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

The cohort table.

Examples

library(PatientProfiles)
library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockPatientProfiles()
cdm$cohort1 |> exitAtDeath()
}

Set cohort end date to the first of a set of column dates

Description

exitAtFirstDate() resets cohort end date based on a set of specified column dates. The first date that occurs is chosen.

Usage

exitAtFirstDate(
  cohort,
  dateColumns,
  cohortId = NULL,
  returnReason = FALSE,
  keepDateColumns = TRUE,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

The cohort table.

Examples

library(CohortConstructor)
library(PatientProfiles)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 <- cdm$cohort1 |>
  addTableIntersectDate(tableName = "observation", nameStyle = "next_obs", order = "first") |>
  addFutureObservation(futureObservationType = "date", name = "cohort1")

cdm$cohort1 |>
  exitAtFirstDate(dateColumns = c("next_obs", "future_observation"))
}

Set cohort end date to the last of a set of column dates

Description

exitAtLastDate() resets cohort end date based on a set of specified column dates. The last date that occurs is chosen.

Usage

exitAtLastDate(
  cohort,
  dateColumns,
  cohortId = NULL,
  returnReason = FALSE,
  keepDateColumns = TRUE,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

The cohort table.

Examples

library(CohortConstructor)
library(PatientProfiles)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 <- cdm$cohort1 |>
  addTableIntersectDate(tableName = "observation", nameStyle = "next_obs", order = "first") |>
  addFutureObservation(futureObservationType = "date", name = "cohort1")

cdm$cohort1 |>
  exitAtLastDate(dateColumns = c("next_obs", "future_observation"))
}

Set cohort end date to end of observation

Description

exitAtObservationEnd() resets cohort end date based on a set of specified column dates. The last date that occurs is chosen.

This functions changes cohort end date to the end date of the observation period corresponding to the cohort entry. In the case were this generates overlapping records in the cohort, overlapping entries will be merged.

Usage

exitAtObservationEnd(
  cohort,
  cohortId = NULL,
  persistAcrossObservationPeriods = FALSE,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

The cohort table.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 |> exitAtObservationEnd()
}

Helper for consistent documentation of gap.

Description

Helper for consistent documentation of gap.

Arguments

Generate a combination cohort set between the intersection of different cohorts.

Description

intersectCohorts() combines different cohort entries, with those records that overlap combined and kept. Cohort entries are when an individual was in both of the cohorts.

Usage

intersectCohorts(
  cohort,
  cohortId = NULL,
  gap = 0,
  returnNonOverlappingCohorts = FALSE,
  keepOriginalCohorts = FALSE,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

A cohort table.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort3 <- intersectCohorts(cohort = cdm$cohort2, name = "cohort3")

settings(cdm$cohort3)
}

Helper for consistent documentation of keepOriginalCohorts.

Description

Helper for consistent documentation of keepOriginalCohorts.

Arguments

Generate a new cohort matched cohort

Description

matchCohorts() generate a new cohort matched to individuals in an existing cohort. Individuals can be matched based on year of birth and sex. Matching is done at the record level, so if individuals have multiple cohort entries they can be matched to different individuals for each of their records.

Two new cohorts will be created when matching. The first is those cohort entries which were matched ("_sampled" is added to the original cohort name for this cohort). The other is the matches found from the database population ("_matched" is added to the original cohort name for this cohort).

Usage

matchCohorts(
  cohort,
  cohortId = NULL,
  matchSex = TRUE,
  matchYearOfBirth = TRUE,
  ratio = 1,
  keepOriginalCohorts = FALSE,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

A cohort table.

Examples

library(CohortConstructor)
library(dplyr)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$new_matched_cohort <- cdm$cohort2 |>
  matchCohorts(
    name = "new_matched_cohort",
    cohortId = 2,
    matchSex = TRUE,
    matchYearOfBirth = TRUE,
    ratio = 1)
cdm$new_matched_cohort
}

Create measurement-based cohorts

Description

measurementCohort() creates cohorts based on patient records from the measurement or observation tables. It extends the function conceptCohort() by allowing users to specify measurement values associated with those records.

This function supports both concept-based and value-based filtering:

• Either valueAsConcept or valueAsNumber must be provided.

• If one of them is specified (not NULL), only records that satisfy the other filter will be included.

• If both are provided, records that meet either filter will be included.

Usage

measurementCohort(
  cdm,
  conceptSet,
  name,
  valueAsConcept = NULL,
  valueAsNumber = NULL,
  table = NULL,
  useRecordsBeforeObservation = FALSE,
  useSourceFields = FALSE,
  subsetCohort = NULL,
  subsetCohortId = NULL
)

Arguments

Value

A cohort table.

Examples

library(CohortConstructor)
library(omock)
library(dplyr)

cdm <- mockVocabularyTables(concept = tibble(
  concept_id = c(4326744, 4298393, 45770407, 8876, 4124457),
  concept_name = c("Blood pressure", "Systemic blood pressure",
                   "Baseline blood pressure", "millimeter mercury column",
                   "Normal range"),
  domain_id = "Measurement",
  vocabulary_id = c("SNOMED", "SNOMED", "SNOMED", "UCUM", "SNOMED"),
  standard_concept = "S",
  concept_class_id = c("Observable Entity", "Observable Entity",
                       "Observable Entity", "Unit", "Qualifier Value"),
  concept_code = NA_character_,
  valid_start_date = as.Date(NA_character_),
  valid_end_date = as.Date(NA_character_),
  invalid_reason = NA_character_
)) |>
  mockCdmFromTables(tables = list(
    measurement = tibble(
      measurement_id = 1:4L,
      person_id = c(1L, 1L, 2L, 3L),
      measurement_concept_id = c(4326744L, 4298393L, 4298393L, 45770407L),
      measurement_date = as.Date(c("2000-07-01", "2000-12-11", "2002-09-08", "2015-02-19")),
      measurement_type_concept_id = 0L,
      value_as_number = c(100, 125, NA, NA),
      value_as_concept_id = c(0L, 0L, 0L, 4124457L),
      unit_concept_id = c(8876L, 8876L, 0L, 0L)
   )
 ))

# create one cohort of blood pressure measurements indicating normal levels
cdm$cohort <- measurementCohort(
  cdm = cdm,
  name = "cohort",
  conceptSet = list("blood_pressure" = c(4326744, 4298393, 45770407)),
  valueAsConcept = list("normal_blood_preassure" = c(4124457)),
  valueAsNumber = list("normal_blood_preassure" = list("8876" = c(70, 120))),
  useRecordsBeforeObservation = FALSE
)

cdm$cohort

# create two cohorts of blood preassure measurements, one with results
# indicating normal blood pressure and the other inidcating high

cdm$cohort2 <- measurementCohort(
  cdm = cdm,
  name = "cohort2",
  conceptSet = list("blood_pressure" = c(4326744, 4298393, 45770407)),
  valueAsConcept = list(
    "normal_blood_pressure" = 4124457,
    "high_blood_pressure" = 4328749
  ),
  valueAsNumber = list(
    "normal_blood_pressure" = list("8876" = c(70, 120)),
    "high_blood_pressure" = list("8876" = c(121, 200))
  ),
  useRecordsBeforeObservation = TRUE
)

cdm$cohort2 |> settings()

Function to create a mock cdm reference for CohortConstructor

Description

mockCohortConstructor() creates an example dataset that can be used for demonstrating and testing the package

Usage

mockCohortConstructor(source = "local")

Arguments

Value

cdm object

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm
}

Helper for consistent documentation of name.

Description

Helper for consistent documentation of name.

Arguments

Set cohort start or cohort end

Description

Set cohort start or cohort end

Usage

padCohortDate(
  cohort,
  days,
  cohortDate = "cohort_start_date",
  indexDate = "cohort_start_date",
  collapse = TRUE,
  requireFullContribution = FALSE,
  cohortId = NULL,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

Cohort table

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 |>
  padCohortDate(
    cohortDate = "cohort_end_date",
    indexDate = "cohort_start_date",
    days = 10)
}

Add days to cohort end

Description

padCohortEnd() Adds (or subtracts) a certain number of days to the cohort end date. Note:

• If the days added means that cohort end would be after observation period end date, then observation period end date will be used for cohort exit.

• If the days added means that cohort exit would be after the next cohort start then these overlapping cohort entries will be collapsed.

• If days subtracted means that cohort end would be before cohort start then the cohort entry will be dropped.

Usage

padCohortEnd(
  cohort,
  days,
  collapse = TRUE,
  requireFullContribution = FALSE,
  cohortId = NULL,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

Cohort table

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
# add 10 days to each cohort exit
cdm$cohort1 |>
  padCohortEnd(days = 10)
}

Add days to cohort start

Description

padCohortStart() Adds (or subtracts) a certain number of days to the cohort start date. Note:

• If the days added means that cohort start would be after cohort end then the cohort entry will be dropped.

• If subtracting day means that cohort start would be before observation period start then the cohort entry will be dropped.

Usage

padCohortStart(
  cohort,
  days,
  collapse = TRUE,
  requireFullContribution = FALSE,
  cohortId = NULL,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

Cohort table

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
# add 10 days to each cohort entry
cdm$cohort1 |>
  padCohortStart(days = 10)
}

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

omopgenerics

attrition, bind, cohortCodelist, cohortCount, settings, tableName

PatientProfiles

endDateColumn, startDateColumn

Utility function to change the name of a cohort.

Description

Utility function to change the name of a cohort.

Usage

renameCohort(cohort, newCohortName, cohortId = NULL)

Arguments

Value

A cohort_table object.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

settings(cdm$cohort1)

cdm$cohort1 <- cdm$cohort1 |>
  renameCohort(newCohortName = "new_name")

settings(cdm$cohort1)
}

Restrict cohort on age

Description

requireAge() filters cohort records, keeping only records where individuals satisfy the specified age criteria.

Usage

requireAge(
  cohort,
  ageRange,
  cohortId = NULL,
  indexDate = "cohort_start_date",
  atFirst = FALSE,
  name = tableName(cohort)
)

Arguments

Value

The cohort table with only records for individuals satisfying the age requirement

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 |>
  requireAge(indexDate = "cohort_start_date",
             ageRange = list(c(18, 65)))
}

Require cohort subjects are present (or absence) in another cohort

Description

requireCohortIntersect() filters a cohort table based on a requirement that an individual is seen (or not seen) in another cohort in some time window around an index date.

Usage

requireCohortIntersect(
  cohort,
  targetCohortTable,
  window,
  intersections = c(1, Inf),
  cohortId = NULL,
  targetCohortId = NULL,
  cohortCombinationCriteria = "all",
  indexDate = "cohort_start_date",
  targetStartDate = "cohort_start_date",
  targetEndDate = "cohort_end_date",
  censorDate = NULL,
  atFirst = FALSE,
  name = tableName(cohort)
)

Arguments

Value

Cohort table with only those entries satisfying the criteria

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 |>
  requireCohortIntersect(targetCohortTable = "cohort2",
                         targetCohortId = 1,
                         indexDate = "cohort_start_date",
                         window = c(-Inf, 0))
}

Require cohort subjects to have (or not have) events of a concept list

Description

requireConceptIntersect() filters a cohort table based on a requirement that an individual is seen (or not seen) to have events related to a concept list in some time window around an index date.

Usage

requireConceptIntersect(
  cohort,
  conceptSet,
  window,
  intersections = c(1, Inf),
  cohortId = NULL,
  indexDate = "cohort_start_date",
  targetStartDate = "event_start_date",
  targetEndDate = "event_end_date",
  inObservation = TRUE,
  censorDate = NULL,
  atFirst = FALSE,
  name = tableName(cohort)
)

Arguments

Value

Cohort table

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort2 <-  requireConceptIntersect(
  cohort = cdm$cohort1,
  conceptSet = list(a = 194152),
  window = c(-Inf, 0),
  name = "cohort2")
  }
  

Restrict cohort on patient demographics

Description

requireDemographics() filters cohort records, keeping only records where individuals satisfy the specified demographic criteria.

Usage

requireDemographics(
  cohort,
  cohortId = NULL,
  indexDate = "cohort_start_date",
  ageRange = list(c(0, 150)),
  sex = c("Both"),
  minPriorObservation = 0,
  minFutureObservation = 0,
  atFirst = FALSE,
  name = tableName(cohort)
)

Arguments

Value

The cohort table with only records for individuals satisfying the demographic requirements

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 |>
  requireDemographics(indexDate = "cohort_start_date",
                      ageRange = list(c(18, 65)),
                      sex = "Female",
                      minPriorObservation = 365)
}

Helper for consistent documentation of arguments in requireDemographics.

Description

Helper for consistent documentation of arguments in requireDemographics.

Arguments

Require cohort entries last for a certain number of days

Description

requireDuration() filters cohort records, keeping only those which last for the specified amount of days

Usage

requireDuration(
  cohort,
  daysInCohort,
  cohortId = NULL,
  name = tableName(cohort)
)

Arguments

Value

The cohort table with any cohort entries that last less or more than the required duration dropped

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 |>
  requireDuration(daysInCohort = c(2, Inf))
}

Helper for consistent documentation of requireFullContribution.

Description

Helper for consistent documentation of requireFullContribution.

Arguments

Restrict cohort on future observation

Description

requireFutureObservation() filters cohort records, keeping only records where individuals satisfy the specified future observation criteria.

Usage

requireFutureObservation(
  cohort,
  minFutureObservation,
  cohortId = NULL,
  indexDate = "cohort_start_date",
  atFirst = FALSE,
  name = tableName(cohort)
)

Arguments

Value

The cohort table with only records for individuals satisfying the future observation requirement

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 |>
  requireFutureObservation(indexDate = "cohort_start_date",
                           minFutureObservation = 30)
}

Require that an index date is within a date range

Description

requireInDateRange() filters cohort records, keeping only those for which the index date is within the specified date range.

Usage

requireInDateRange(
  cohort,
  dateRange,
  cohortId = NULL,
  indexDate = "cohort_start_date",
  atFirst = FALSE,
  name = tableName(cohort)
)

Arguments

Value

The cohort table with any cohort entries outside of the date range dropped

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 |>
  requireInDateRange(indexDate = "cohort_start_date",
                     dateRange = as.Date(c("2010-01-01", "2019-01-01")))
}

Helper for consistent documentation of arguments in requireIntersect functions.

Description

Helper for consistent documentation of arguments in requireIntersect functions.

Arguments

Restrict cohort to specific entry

Description

requireIsFirstEntry() filters cohort records, keeping only the first cohort entry per person.

Usage

requireIsEntry(cohort, entryRange, cohortId = NULL, name = tableName(cohort))

Arguments

Value

A cohort table in a cdm reference.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 <- requireIsEntry(cdm$cohort1, c(1, Inf))
}

Restrict cohort to first entry

Description

requireIsFirstEntry() filters cohort records, keeping only the first cohort entry per person.

Usage

requireIsFirstEntry(cohort, cohortId = NULL, name = tableName(cohort))

Arguments

Value

A cohort table in a cdm reference.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 <- requireIsFirstEntry(cdm$cohort1)
}

Restrict cohort to last entry per person

Description

requireIsLastEntry() filters cohort records, keeping only the last cohort entry per person.

Usage

requireIsLastEntry(cohort, cohortId = NULL, name = tableName(cohort))

Arguments

Value

A cohort table in a cdm reference.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 <- requireIsLastEntry(cdm$cohort1)
}

Filter cohorts to keep only records for those with a minimum amount of subjects

Description

requireMinCohortCount() filters an existing cohort table, keeping only records from cohorts with a minimum number of individuals

Usage

requireMinCohortCount(
  cohort,
  minCohortCount,
  cohortId = NULL,
  updateSettings = FALSE,
  name = tableName(cohort)
)

Arguments

Value

Cohort table

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 |>
requireMinCohortCount(5)
}

Restrict cohort on prior observation

Description

requirePriorObservation() filters cohort records, keeping only records where individuals satisfy the specified prior observation criteria.

Usage

requirePriorObservation(
  cohort,
  minPriorObservation,
  cohortId = NULL,
  indexDate = "cohort_start_date",
  atFirst = FALSE,
  name = tableName(cohort)
)

Arguments

Value

The cohort table with only records for individuals satisfying the prior observation requirement

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 |>
  requirePriorObservation(indexDate = "cohort_start_date",
                          minPriorObservation = 365)
}

Restrict cohort on sex

Description

requireSex() filters cohort records, keeping only records where individuals satisfy the specified sex criteria.

Usage

requireSex(
  cohort,
  sex,
  cohortId = NULL,
  atFirst = FALSE,
  name = tableName(cohort)
)

Arguments

Value

The cohort table with only records for individuals satisfying the sex requirement

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 |>
  requireSex(sex = "Female")
}

Require cohort subjects are present in another clinical table

Description

requireTableIntersect() filters a cohort table based on a requirement that an individual is seen (or not seen) to have a record (or no records) in a clinical table in some time window around an index date.

Usage

requireTableIntersect(
  cohort,
  tableName,
  window,
  intersections = c(1, Inf),
  cohortId = NULL,
  indexDate = "cohort_start_date",
  targetStartDate = startDateColumn(tableName),
  targetEndDate = endDateColumn(tableName),
  inObservation = TRUE,
  censorDate = NULL,
  atFirst = FALSE,
  name = tableName(cohort)
)

Arguments

Value

Cohort table

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 |>
  requireTableIntersect(tableName = "drug_exposure",
                            indexDate = "cohort_start_date",
                            window = c(-Inf, 0))
}

Sample a cohort table for a given number of individuals.

Description

sampleCohorts() samples an existing cohort table for a given number of people. All records of these individuals are preserved.

Usage

sampleCohorts(cohort, n, cohortId = NULL, name = tableName(cohort))

Arguments

Value

Cohort table with the specified cohorts sampled.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort2 |> sampleCohorts(cohortId = 1, n = 10)
}

Helper for consistent documentation of .softValidation.

Description

Helper for consistent documentation of .softValidation.

Arguments

Create a new cohort table from stratifying an existing one

Description

stratifyCohorts() creates new cohorts, splitting an existing cohort based on specified columns on which to stratify on.

Usage

stratifyCohorts(
  cohort,
  strata,
  cohortId = NULL,
  removeStrata = TRUE,
  name = tableName(cohort)
)

Arguments

Value

Cohort table stratified.

Examples

library(CohortConstructor)
library(PatientProfiles)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$my_cohort <- cdm$cohort1 |>
  addAge(ageGroup = list("child" = c(0, 17), "adult" = c(18, Inf))) |>
  addSex(name = "my_cohort") |>
  stratifyCohorts(
    strata = list("sex", c("sex", "age_group")), name = "my_cohort"
  )

cdm$my_cohort

settings(cdm$my_cohort)

attrition(cdm$my_cohort)
}

Generate a cohort table keeping a subset of cohorts.

Description

subsetCohorts() filters an existing cohort table, keeping only the records from cohorts that are specified.

Usage

subsetCohorts(cohort, cohortId, name = tableName(cohort))

Arguments

Value

Cohort table with only cohorts in cohortId.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 |>
  subsetCohorts(cohortId = 1)
}

Trim cohort on patient demographics

Description

trimDemographics() resets the cohort start and end date based on the specified demographic criteria is satisfied.

Usage

trimDemographics(
  cohort,
  cohortId = NULL,
  ageRange = NULL,
  sex = NULL,
  minPriorObservation = NULL,
  minFutureObservation = NULL,
  name = tableName(cohort)
)

Arguments

Value

The cohort table with only records for individuals satisfying the demographic requirements

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 |>
  trimDemographics(ageRange = list(c(10, 30)))
}

Trim cohort dates to be within a certain interval of days

Description

trimDuration() resets the cohort start and end date, keeping only those which include the specified amount of days

Usage

trimDuration(cohort, daysInCohort, cohortId = NULL, name = tableName(cohort))

Arguments

Value

The cohort table with any cohort entries that last less or more than the required duration dropped

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 |>
  requireDuration(daysInCohort = c(2, Inf))
}

Trim cohort dates to be within a date range

Description

trimToDateRange() resets the cohort start and end date based on the specified date range.

Usage

trimToDateRange(
  cohort,
  dateRange,
  cohortId = NULL,
  startDate = "cohort_start_date",
  endDate = "cohort_end_date",
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

The cohort table with record timings updated to only be within the date range. Any records with all time outside of the range will have been dropped.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()
cdm$cohort1 |>
  trimToDateRange(startDate = "cohort_start_date",
                  endDate = "cohort_end_date",
                  dateRange = as.Date(c("2015-01-01",
                                        "2015-12-31")))
}

Generate cohort from the union of different cohorts

Description

unionCohorts() combines different cohort entries, with those records that overlap combined and kept. Cohort entries are when an individual was in either of the cohorts.

Usage

unionCohorts(
  cohort,
  cohortId = NULL,
  gap = 0,
  cohortName = NULL,
  keepOriginalCohorts = FALSE,
  name = tableName(cohort)
)

Arguments

Value

A cohort table.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort2 <- cdm$cohort2 |>
  unionCohorts()

settings(cdm$cohort2)

}

Helper for consistent documentation of window.

Description

Helper for consistent documentation of window.

Arguments

Generate a new cohort table restricting cohort entries to certain years

Description

yearCohorts() splits a cohort into multiple cohorts, one for each year.

Usage

yearCohorts(
  cohort,
  years,
  cohortId = NULL,
  name = tableName(cohort),
  .softValidation = FALSE
)

Arguments

Value

A cohort table.

Examples

library(CohortConstructor)
if(isTRUE(omock::isMockDatasetDownloaded("GiBleed"))){
cdm <- mockCohortConstructor()

cdm$cohort1 <- cdm$cohort1 |>
  yearCohorts(years = 2000:2002)

settings(cdm$cohort1)
}