Updating cohort start and end dates
Source:vignettes/a05_update_cohort_start_end.Rmd
a05_update_cohort_start_end.RmdIntroduction
Accurately defining cohort entry and exit dates is crucial in
observational research to ensure the validity of study findings. The
CohortConstructor package provides several functions to
adjust these dates based on specific criteria, and this vignette
demonstrates how to use them.
Functions to update cohort dates can be categorized into four groups:
Exit at Specific Date Functions: Adjust the cohort end date to predefined events (observation end and death date).
Cohort Entry or Exit Based on Other Date Columns: Modify cohort start or end dates to the earliest or latests from a set of date columns.
Trim Dates Functions: Restrict cohort entries based on demographic criteria or specific date ranges.
Pad Dates Functions: Adjust cohort start or end dates by adding or subtracting a specified number of days.
We’ll explore each category in the following sections.
First, we’ll connect to the Eunomia synthetic data and create a mock cohort of women in the database to use as example in the vignette.
library(CohortConstructor)
library(CohortCharacteristics)
library(PatientProfiles)
library(CDMConnector)
if (Sys.getenv("EUNOMIA_DATA_FOLDER") == ""){
Sys.setenv("EUNOMIA_DATA_FOLDER" = file.path(tempdir(), "eunomia"))}
if (!dir.exists(Sys.getenv("EUNOMIA_DATA_FOLDER"))){ dir.create(Sys.getenv("EUNOMIA_DATA_FOLDER"))
downloadEunomiaData()
}
#>
#> Download completed!
con <- DBI::dbConnect(duckdb::duckdb(), dbdir = CDMConnector::eunomiaDir())
#> Creating CDM database /tmp/Rtmp7MQ6qO/eunomia/GiBleed_5.3.zip
cdm <- CDMConnector::cdmFromCon(con, cdmSchema = "main",
writeSchema = "main", writePrefix = "my_study_")
cdm$cohort <- demographicsCohort(cdm = cdm, name = "cohort", sex = "Female")
#> ℹ Building new trimmed cohort
#> Adding demographics information
#> Creating initial cohort
#> Trim sex
#> ✔ Cohort trimmedExit at Specific Date
exitAtObservationEnd()
The exitAtObservationEnd() function updates the cohort
end date to the end of the observation period for each subject. This
ensures that the cohort exit does not extend beyond the period during
which data is available for the subject.
cdm$cohort_observation_end <- cdm$cohort |>
exitAtObservationEnd(name = "cohort_observation_end")As cohort entries cannot overlap, updating the end date to the observation end may result in overlapping records. In such cases, overlapping records are collapsed into a single entry (starting at the earliest entry and ending at the end of observation).
This function has an argument limitToCurrentPeriod to
consider cases when a subject may have more than one observation period.
If limitToCurrentPeriod = TRUE (default) end date will be
set to the end of the observation period where the record is registered.
If limitToCurrentPeriod = FALSE, in addition to updating
the cohort end to the allocated observation end, cohort entries are
created for each of the subsequent observation periods.
exitAtDeath()
The exitAtDeath() function sets the cohort end date to
the recorded death date of the subject.
By default, it keeps the end date of subjects who do not have a death
record unmodified; however, these can be dropped with the argument
requireDeath.
cdm$cohort_death <- cdm$cohort |>
exitAtDeath(requireDeath = TRUE, name = "cohort_death")Cohort Entry or Exit Based on Other Date Columns
entryAtFirstDate()
The entryAtFirstDate() function updates the cohort start
date to the earliest date among specified columns.
Next we want to set the entry date to the first of: diclofenac or acetaminophen prescriptions after cohort start, or cohort end date.
# create cohort with of drugs diclofenac and acetaminophen
cdm$medications <- conceptCohort(
cdm = cdm, name = "medications",
conceptSet = list("diclofenac" = 1124300, "acetaminophen" = 1127433)
)
#> Warning: ! `codelist` casted to integers.
#> ℹ Subsetting table drug_exposure using 2 concepts with domain: drug.
#> ℹ Combining tables.
#> ℹ Creating cohort attributes.
#> ℹ Applying cohort requirements.
#> ℹ Merging overlapping records.
#> ✔ Cohort medications created.
# add date first ocurrence of these drugs from index date
cdm$cohort_dates <- cdm$cohort |>
addCohortIntersectDate(
targetCohortTable = "medications",
nameStyle = "{cohort_name}",
name = "cohort_dates"
)
# set cohort start at the first ocurrence of one of the drugs, or the end date
cdm$cohort_entry_first <- cdm$cohort_dates |>
entryAtFirstDate(
dateColumns = c("diclofenac", "acetaminophen", "cohort_end_date"),
name = "cohort_entry_first"
)
#> Joining with `by = join_by(cohort_definition_id, subject_id, cohort_end_date)`
cdm$cohort_entry_first
#> # Source: table<my_study_cohort_entry_first> [?? x 7]
#> # Database: DuckDB v1.2.1 [unknown@Linux 6.8.0-1021-azure:R 4.4.3//tmp/Rtmp7MQ6qO/file27af59da6051.duckdb]
#> cohort_definition_id subject_id cohort_start_date cohort_end_date
#> <int> <int> <date> <date>
#> 1 1 729 2000-01-22 2019-03-30
#> 2 1 2620 1989-01-31 2018-12-11
#> 3 1 3352 1981-02-10 2018-11-16
#> 4 1 3486 1969-08-05 2019-03-30
#> 5 1 3719 1964-02-04 2019-02-12
#> 6 1 4092 1986-12-26 2019-05-02
#> 7 1 4491 1975-05-02 2019-06-23
#> 8 1 2409 1993-11-12 2019-06-15
#> 9 1 3921 1994-02-23 2017-10-10
#> 10 1 4217 1976-06-11 2019-06-05
#> # ℹ more rows
#> # ℹ 3 more variables: entry_reason <chr>, diclofenac <date>,
#> # acetaminophen <date>
entryAtLastDate()
The entryAtLastDate() function works similarly to
entryAtFirstDate(), however now the selected column is the
latest date among specified columns.
cdm$cohort_entry_last <- cdm$cohort_dates |>
entryAtLastDate(
dateColumns = c("diclofenac", "acetaminophen", "cohort_end_date"),
keepDateColumns = FALSE,
name = "cohort_entry_last"
)
cdm$cohort_entry_last
#> # Source: table<my_study_cohort_entry_last> [?? x 5]
#> # Database: DuckDB v1.2.1 [unknown@Linux 6.8.0-1021-azure:R 4.4.3//tmp/Rtmp7MQ6qO/file27af59da6051.duckdb]
#> cohort_definition_id subject_id cohort_start_date cohort_end_date
#> <int> <int> <date> <date>
#> 1 1 486 2019-02-14 2019-02-14
#> 2 1 1005 2018-11-20 2018-11-20
#> 3 1 2815 2019-05-31 2019-05-31
#> 4 1 3157 2019-03-08 2019-03-08
#> 5 1 3194 1983-04-05 1983-04-05
#> 6 1 3330 2017-10-22 2017-10-22
#> 7 1 3993 2019-02-05 2019-02-05
#> 8 1 600 2018-08-09 2018-08-09
#> 9 1 1560 2019-02-11 2019-02-11
#> 10 1 2147 2019-01-06 2019-01-06
#> # ℹ more rows
#> # ℹ 1 more variable: entry_reason <chr>In this example, we set keepDateColumns to FALSE, which
drops columns in dateColumns.
exitAtFirstDate()
The exitAtFirstDate() function updates the cohort end
date to the earliest date among specified columns.
For instance, next we want the exit to be observation end, except if there is a record of diclofenac or acetaminophen, in which case that would be the end:
cdm$cohort_exit_first <- cdm$cohort_dates |>
addFutureObservation(futureObservationType = "date", name = "cohort_exit_first") |>
exitAtFirstDate(
dateColumns = c("future_observation", "acetaminophen", "diclofenac"),
keepDateColumns = FALSE
)
cdm$cohort_exit_first
#> # Source: table<my_study_cohort_exit_first> [?? x 5]
#> # Database: DuckDB v1.2.1 [unknown@Linux 6.8.0-1021-azure:R 4.4.3//tmp/Rtmp7MQ6qO/file27af59da6051.duckdb]
#> cohort_definition_id subject_id cohort_start_date cohort_end_date exit_reason
#> <int> <int> <date> <date> <chr>
#> 1 1 63 1955-12-15 1990-09-14 acetaminop…
#> 2 1 621 1912-08-21 1953-11-29 diclofenac
#> 3 1 774 1966-07-25 1983-03-27 acetaminop…
#> 4 1 967 1932-10-15 1939-01-14 acetaminop…
#> 5 1 2724 1954-05-24 1997-10-30 acetaminop…
#> 6 1 4979 1976-07-24 1978-07-14 acetaminop…
#> 7 1 1820 1978-02-07 1984-01-09 acetaminop…
#> 8 1 2409 1978-10-02 1993-11-12 acetaminop…
#> 9 1 2961 1971-09-26 2005-12-28 acetaminop…
#> 10 1 3065 1972-05-11 1976-10-19 acetaminop…
#> # ℹ more rows
exitAtLastDate()
Similarly, the exitAtLastDate() function sets the cohort
end date to the latest date among specified columns.
cdm$cohort_exit_last <- cdm$cohort_dates |>
exitAtLastDate(
dateColumns = c("cohort_end_date", "acetaminophen", "diclofenac"),
returnReason = FALSE,
keepDateColumns = FALSE,
name = "cohort_exit_last"
)
cdm$cohort_exit_last
#> # Source: table<my_study_cohort_exit_last> [?? x 4]
#> # Database: DuckDB v1.2.1 [unknown@Linux 6.8.0-1021-azure:R 4.4.3//tmp/Rtmp7MQ6qO/file27af59da6051.duckdb]
#> cohort_definition_id subject_id cohort_start_date cohort_end_date
#> <int> <int> <date> <date>
#> 1 1 758 1973-03-25 2018-06-03
#> 2 1 1656 1977-11-26 2018-01-27
#> 3 1 2156 1964-07-23 2019-03-21
#> 4 1 2736 1969-08-07 2019-06-13
#> 5 1 3248 1945-07-13 2019-06-07
#> 6 1 3315 1957-04-28 2018-07-01
#> 7 1 299 1961-12-09 2019-01-19
#> 8 1 1683 1971-07-22 2017-08-10
#> 9 1 2115 1961-09-25 2018-11-05
#> 10 1 2483 1944-03-04 1987-06-13
#> # ℹ more rowsIn this last example, the return cohort doesn’t have the specified
date columns, neither the “reason” column indicating which date was used
for entry/exit. These was set with the keepDateColumns and
returnReason arguments, common throughout the functions in
this category.
Trim Dates Functions
trimDemographics()
The trimDemographics() function restricts the cohort
based on patient demographics. This means that cohort start and end
dates are moved (within the original cohort entry dates) to ensure that
individuals meet specific demographic criteria throughout their cohort
participation. If individuals do not satisfy the criteria at any point
during their cohort period, their records are excluded.
For instance, if we trim using an age range from 18 to 65, individuals will only contribute in the cohort form the day they are 18 or older, up to the day before turning 66 (or before if they leave the database).
cdm$cohort_trim <- cdm$cohort |>
trimDemographics(ageRange = c(18, 65), name = "cohort_trim")
#> ℹ Building new trimmed cohort
#> Adding demographics information
#> Creating initial cohort
#> Trim age
#> ✔ Cohort trimmed
trimToDateRange()
The trimToDateRange() function confines cohort entry and
exit dates within a specified date range, ensuring that cohort periods
align with the defined timeframe. If only the start or end of a range is
required, the other can be set to NA.
For example, to restrict cohort dates to be on or after January 1st, 2015:
# Trim cohort dates to be within the year 2000
cdm$cohort_trim <- cdm$cohort_trim |>
trimToDateRange(dateRange = as.Date(c("2015-01-01", NA)))Pad Dates Functions
padCohortStart()
The padCohortStart() function adds (or subtracts) a
specified number of days to the cohort start date.
For example, to subtract 50 days from the cohort start date:
# Substract 50 days to cohort start
cdm$cohort <- cdm$cohort |> padCohortStart(days = -50, collapse = FALSE)When subtracting days, it may result in cohort start dates preceding
the observation period start. By default, such entries are corrected to
the observation period start. To drop these entries instead, set the
padObservation argument to FALSE.
Additionally, adjusting cohort start dates may lead to overlapping
entries for the same subject. The collapse argument manages
this: if TRUE, merges overlapping entries into a single record with the
earliest start and latest end date (default), if FALSE retains only the
first of the overlapping entries.
padCohortEnd()
Similarly, the padCohortEnd() function adjusts the
cohort end date by adding (or subtracting) a specified number of
days.
The example below adds 1000 days to cohort end date, while dropping records that are outside of observation after adding days.
cdm$cohort_pad <- cdm$cohort |>
padCohortEnd(days = 1000, padObservation = FALSE, name = "cohort_pad")Additionally, days to add can also be specified with a numeric column in the cohort, which allows to add a specific number of days for each record:
cdm$cohort <- cdm$cohort %>%
dplyr::mutate(days_to_add = !!CDMConnector::datediff("cohort_start_date", "cohort_end_date")) |>
padCohortEnd(days = "days_to_add", padObservation = FALSE)
padCohortDate()
The padCohortDate() function provides a more flexible
approach by allowing adjustments to either the cohort start or end date
based on specified parameters. You can define which date to adjust
(cohortDate), the reference date for the adjustment
(indexDate), and the number of days to add or subtract.
For example, to set the cohort end date to be 365 days after the cohort start date:
cdm$cohort <- cdm$cohort |>
padCohortDate(days = 365, cohortDate = "cohort_end_date", indexDate = "cohort_start_date")Cohort ID argument
For all these functions, the cohortId argument specifies which cohorts to modify. This allows for targeted adjustments without altering other cohorts. For instance, to add 10 days to the end date of the acetaminophen cohort and 20 days to the diclofenac cohort we can do the following:
cdm$medications <- cdm$medications |>
padCohortDate(days = 10, cohortId = "acetaminophen") |>
padCohortDate(days = 20, cohortId = "diclofenac")