From 147d70adade5b6a8a9d9fb97503e23b1afac354a Mon Sep 17 00:00:00 2001 From: jreps Date: Thu, 19 Sep 2024 13:17:06 -0400 Subject: [PATCH 1/4] restricting cases to first outcome in TAR - restricting cases to first outcome in TAR --- DESCRIPTION | 2 +- inst/sql/sql_server/CaseCohortsPart1.sql | 2 +- inst/sql/sql_server/CaseCohortsPart2.sql | 15 +++++++++++---- 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 9ac4a24..9cb8c0a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: Characterization Type: Package Title: Characterizations of Cohorts -Version: 2.0.1 +Version: 2.0.1.9000 Date: 2024-08-21 Authors@R: c( person("Jenna", "Reps", , "reps@ohdsi.org", role = c("aut", "cre")), diff --git a/inst/sql/sql_server/CaseCohortsPart1.sql b/inst/sql/sql_server/CaseCohortsPart1.sql index 6069163..acd1afc 100644 --- a/inst/sql/sql_server/CaseCohortsPart1.sql +++ b/inst/sql/sql_server/CaseCohortsPart1.sql @@ -50,7 +50,7 @@ and datediff(day, op.observation_period_start_date, o.cohort_start_date) >= @min IF OBJECT_ID('tempdb..#case_exclude', 'U') IS NOT NULL DROP TABLE #case_exclude; -- people with outcome prior -select +select distinct t.subject_id, t.cohort_start_date, t.cohort_end_date, diff --git a/inst/sql/sql_server/CaseCohortsPart2.sql b/inst/sql/sql_server/CaseCohortsPart2.sql index 27b1340..e8eb757 100644 --- a/inst/sql/sql_server/CaseCohortsPart2.sql +++ b/inst/sql/sql_server/CaseCohortsPart2.sql @@ -2,13 +2,13 @@ -- 1) get all the people with the outcome in TAR IF OBJECT_ID('tempdb..#cases_tar', 'U') IS NOT NULL DROP TABLE #cases_tar; --- cases +-- cases (first outcome date) select t.subject_id, t.cohort_start_date, t.cohort_end_date, -o.cohort_start_date as outcome_start_date, -o.cohort_end_date as outcome_end_date, +min(o.cohort_start_date) as outcome_start_date, +min(o.cohort_end_date) as outcome_end_date, t.cohort_definition_id as target_cohort_id, o.cohort_definition_id as outcome_cohort_id into #cases_tar @@ -19,7 +19,14 @@ where o.cohort_start_date <= dateadd(day, @tar_end, t.@tar_end_anchor) and -- outcome starts (ends?) after TAR start -o.cohort_start_date >= dateadd(day, @tar_start, t.@tar_start_anchor); +o.cohort_start_date >= dateadd(day, @tar_start, t.@tar_start_anchor) +-- make sure to only get first outcome date during TAR +group by +t.subject_id, +t.cohort_start_date, +t.cohort_end_date, +t.cohort_definition_id, +o.cohort_definition_id; -- add the cases for specific TAR insert into #cases From 6febabd581b3ac66f1edf3d8b3582c3a407ca81f Mon Sep 17 00:00:00 2001 From: jreps Date: Thu, 19 Sep 2024 13:19:06 -0400 Subject: [PATCH 2/4] Update R_CMD_check_Hades.yaml - updating download and upload artifact for github actions --- .github/workflows/R_CMD_check_Hades.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/R_CMD_check_Hades.yaml b/.github/workflows/R_CMD_check_Hades.yaml index 7280c66..23d9737 100644 --- a/.github/workflows/R_CMD_check_Hades.yaml +++ b/.github/workflows/R_CMD_check_Hades.yaml @@ -97,7 +97,7 @@ jobs: - name: Upload source package if: success() && runner.os == 'macOS' && github.event_name != 'pull_request' && github.ref == 'refs/heads/main' - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@v4 with: name: package_tarball path: check/*.tar.gz @@ -167,7 +167,7 @@ jobs: - name: Download package tarball if: ${{ env.new_version != '' }} - uses: actions/download-artifact@v2 + uses: actions/download-artifact@v4 with: name: package_tarball From 6e2e511f3959380eb613fade9811ad9b8bc2fbb6 Mon Sep 17 00:00:00 2001 From: jreps Date: Mon, 7 Oct 2024 16:11:47 -0400 Subject: [PATCH 3/4] adding spec to website - adding spec to website --- docs/404.html | 11 +- docs/articles/InstallationGuide.html | 13 +- docs/articles/Specification.html | 1998 +++++++++++++++++ docs/articles/UsingPackage.html | 79 +- docs/articles/images/dcrc_dechal_summary.png | Bin 0 -> 72716 bytes docs/articles/images/dcrc_example_data.png | Bin 0 -> 163457 bytes docs/articles/images/dcrc_rechal_summary.png | Bin 0 -> 73868 bytes docs/articles/images/tte_example_data.png | Bin 0 -> 163457 bytes .../images/tte_example_data_with_times.png | Bin 0 -> 173787 bytes docs/articles/index.html | 13 +- docs/authors.html | 13 +- docs/index.html | 11 +- docs/news/index.html | 16 +- docs/pkgdown.yml | 7 +- docs/pull_request_template.html | 7 +- docs/reference/Characterization-package.html | 11 +- docs/reference/cleanIncremental.html | 16 +- docs/reference/cleanNonIncremental.html | 16 +- ...computeDechallengeRechallengeAnalyses.html | 11 +- ...puteRechallengeFailCaseSeriesAnalyses.html | 11 +- .../reference/computeTimeToEventAnalyses.html | 11 +- .../createAggregateCovariateSettings.html | 11 +- .../createCharacterizationSettings.html | 11 +- .../createCharacterizationTables.html | 11 +- .../createDechallengeRechallengeSettings.html | 11 +- .../createDuringCovariateSettings.html | 19 +- docs/reference/createSqliteDatabase.html | 11 +- docs/reference/createTimeToEventSettings.html | 11 +- .../exportDechallengeRechallengeToCsv.html | 11 +- .../exportRechallengeFailCaseSeriesToCsv.html | 11 +- docs/reference/exportTimeToEventToCsv.html | 11 +- docs/reference/getDbDuringCovariateData.html | 11 +- docs/reference/index.html | 17 +- docs/reference/insertResultsToDatabase.html | 11 +- .../loadCharacterizationSettings.html | 11 +- .../runCharacterizationAnalyses.html | 11 +- .../saveCharacterizationSettings.html | 11 +- docs/reference/viewCharacterization.html | 11 +- docs/sitemap.xml | 7 +- man/createDuringCovariateSettings.Rd | 8 +- vignettes/Specification.Rmd | 809 +++++++ vignettes/images/dcrc_dechal_summary.png | Bin 0 -> 72716 bytes vignettes/images/dcrc_example_data.png | Bin 0 -> 163457 bytes vignettes/images/dcrc_rechal_summary.png | Bin 0 -> 73868 bytes vignettes/images/tte_example_data.png | Bin 0 -> 163457 bytes .../images/tte_example_data_with_times.png | Bin 0 -> 173787 bytes 46 files changed, 3107 insertions(+), 162 deletions(-) create mode 100644 docs/articles/Specification.html create mode 100644 docs/articles/images/dcrc_dechal_summary.png create mode 100644 docs/articles/images/dcrc_example_data.png create mode 100644 docs/articles/images/dcrc_rechal_summary.png create mode 100644 docs/articles/images/tte_example_data.png create mode 100644 docs/articles/images/tte_example_data_with_times.png create mode 100644 vignettes/Specification.Rmd create mode 100644 vignettes/images/dcrc_dechal_summary.png create mode 100644 vignettes/images/dcrc_example_data.png create mode 100644 vignettes/images/dcrc_rechal_summary.png create mode 100644 vignettes/images/tte_example_data.png create mode 100644 vignettes/images/tte_example_data_with_times.png diff --git a/docs/404.html b/docs/404.html index 7ee4ee6..a37d3dc 100644 --- a/docs/404.html +++ b/docs/404.html @@ -6,7 +6,7 @@ Page not found (404) • Characterization - + @@ -32,7 +32,7 @@ Characterization - 2.0.0 + 2.0.1.9000 @@ -60,6 +60,9 @@
  • Characterization Installation Guide
    • +
  • + Characterization Package Specification +
  • Using Characterization Package
    • @@ -71,7 +74,7 @@
    • - + hadesLogo
    • @@ -96,7 +99,7 @@

      Characterization Installation Guide

      Jenna Reps

      -

      2024-08-07

      +

      2024-10-07

      Source:       vignettes/InstallationGuide.Rmd @@ -230,7 +233,7 @@

      Acknowledgments

      -

      Site built with pkgdown 2.0.9.

      +

      Site built with pkgdown 2.0.7.

      diff --git a/docs/articles/Specification.html b/docs/articles/Specification.html new file mode 100644 index 0000000..d20a017 --- /dev/null +++ b/docs/articles/Specification.html @@ -0,0 +1,1998 @@ + + + + + + + +Characterization Package Specification • Characterization + + + + + + + + + + + + +
      +
      + + + + +
      +
      +
      +

      Characterization Package Specification

      +

      Jenna Reps

      + +

      2024-10-07

      + + Source: vignettes/Specification.Rmd + + +
      + + + + +
      +

      Time-to-event +

      +
      +

      Inputs +

      +

      A vector of targetIds and a vector of outcomeIds

      +
      +
      +

      Output +

      +

      Summary data.frame with the counts of how often an outcome occurred +within a time-period relative to the first target index date for each +combination of target and outcome. The counts are stratified by whether +the outcome was first event or subsequent and the timing category for +when the outcome occurred (before first target exposure, during first +target exposure, during a subsequent target exposure, between target +exposures and after last target exposure).

      +
      +
      +

      Worked Example +

      +
      +

      Example Inputs +

      +

      Here we consider the inputs are:

      +
      +targetIds <- c(1)
+outcomeIds <- c(2)
      +

      Consider we have five patients; the target cohort (dates each of the +five patients are exposed to a drug) is in Table 1 and the outcome +cohort (dates each of the five patients have the outcome) is in Table 2. +This is also illustrated in Figures 1 and 2.

      +
      +
      +

      Example Data Image +

      +
      +Figure 1 - Example data for five patients with dates.
      Figure 1 - Example data for five patients with +dates.
      +
      +
      +Figure 2 - Example data for five patients with timing.
      Figure 2 - Example data for five patients with +timing.
      +
      +
      +
      +

      Example Data Table +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example time-to-event data with dates.
      patientIdcohortDefinitionIdcohortStartDatecohortEndDate
      112001-01-202001-01-25
      112001-10-202001-12-05
      212005-09-102005-09-15
      312004-04-022004-05-17
      412002-03-032002-06-12
      412003-02-012003-02-30
      412003-08-042003-08-24
      512005-02-012005-10-08
      512007-04-032007-05-03
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example time-to-event data with timing.
      patientIdcohortDefinitionIdcohortStartDatecohortEndDate
      121999-10-031999-10-08
      122001-10-302001-11-07
      322004-05-162004-05-18
      422002-06-032002-06-14
      422003-02-202003-03-01
      522006-07-212006-08-03
      522008-01-012008-01-09
      +

      For all rows in the outcome table, we calculate the time between the +patients first exposure in the target cohort and the outcome date +(time-to-event), we classify the ‘type’ as the timing of when the +outcome occurs with ‘before first exposure’ meaning the outcome occurs +before the patient is observed in the target cohort, ‘during first’ +means the outcome occurs during the first target cohort exposure, +‘between eras’ means the outcome occurs between target exposures, +‘during subsequent’ means the outcome occurs during a non-first target +exposure and ‘after last exposure’ means the outcome occurs after the +last exposure in the target cohort’s end date for the patient. The +outcome type is classified whether the outcome is the ‘first occurrence’ +or a ‘subsequent occurrence’. Let’s consider patient 1, he has the +outcome twice. The first outcome occurs 475 days before his first target +exposure and his second outcome occurs 283 days after his first target +exposure. The second outcome for patient 1 occurs during a subsequent +target exposure era (not the first). Patient 2 does not have the outcome +so does not contribute to the time-to-event. Patient 3 has her first +(and only) outcome during the first exposure to the drug and 44 days +after she started the drug for the first time. Patient 4 has the outcome +twice, 92 days after the first exposure to the drug and 354 days after. +The first time she has the outcome is during the first exposure to the +drug and the subsequent time she has the outcome is during her second +exposure (subsequent exposure). Patient 5 has the outcome twice, 535 +days after he is first exposure to the drug and 1064 days after. The +first time he has the outcome occurs between drug exposure eras and the +subsequent outcome occurs after the last exposure era. This is +summarized in Table 3.

      + + ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table 3: Time-to-event intermediate summary.
      patientIdoutcomeDatefirstExposureDatetimeToEventtypeoutcomeType
      11999-10-032001-01-20-475Before first exposureFirst
      12001-10-302001-01-20283During subsequentSubsequent
      32004-05-162004-04-0244During firstFirst
      42002-06-032002-03-0392During firstFirst
      42003-02-202002-03-03354During subsequentSubsequent
      52006-07-212005-02-01535Between erasFirst
      52008-01-012005-02-011064After last exposureSubsequent
      +

      The time-to-event output aggregates the summary table into three +different perspectives:

      +
        +

      • 1-day aggregate – this calculates the total number of patients +that have the outcome at each time-to-event day grouped by type and +outcome type. Only looks at outcomes between -100 days and 100 days for +the time-to-event.

        • +

      • 30-day aggregate – this calculates the total number of patients +that have the outcome at each 30-day sliding window for time-to-event +(e.g., 0-29, 30-59, 60-89, etc.) grouped by type and outcome type. Only +looks at outcomes between -1095 days and 1095 days for the +time-to-event.

        • +

      • 365-day aggregate – this calculates the total number of patients +that have the outcome at each 365-day sliding window for time-to-event +(e.g., 0-365, 366-730, 731-1095, etc.) grouped by type and outcome type. +Only looks at outcomes between -1095 days and 1095 days for the +time-to-event.

        • +
      +

      The summary results that would be output by time-to-event are +displayed in Table 4.

      + + ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table 4: Time-to-event output.
      timeTypeTypeoutcomeTypetimeStarttimeEndcount
      1-dayDuring firstFirst44441
      1-dayDuring firstFirst92921
      30-dayBefore first exposureFirst-481-4501
      30-dayDuring firstFirst31601
      30-dayDuring firstFirst911201
      30-dayDuring subsequentSubsequent2713001
      30-dayDuring subsequentSubsequent3313601
      30-dayBetween erasFirst5115401
      30-dayAfter last exposureSubsequent105110801
      365-dayBefore first exposureFirst-731-3651
      365-dayDuring firstFirst13652
      365-dayDuring subsequentSubsequent13652
      365-dayBetween erasFirst3667301
      365-dayAfter last exposureSubsequent73110951
      +
      +
      +
      +
      +

      Dechallenge-rechallenge +

      +
      +

      Inputs +

      +

      A vector of targetIds, a vector of outcomeIds, an integer +dechallengeStopInterval and an integer dechallengeEvaluationWindow.

      +
      +
      +

      Output +

      +

      A summary data.frame with the number of dechallenge and rechallenge +attempts per target and outcome combination plus the number of +dechallange/rechallenge attempts that were successes and failures.

      +
      +
      +

      Worked Example +

      +

      The dechallenge-rechallenge analysis finds out how often a patient +stops the drug due to the occurrence of an outcome and whether the +outcome stops, then it looks at whether people re-exposed have the +outcome start again. In observational data we infer these situations by +finding cases where a patient has the outcome recorded during a drug +exposure and seems to stop the drug within <dechallenge stop interval +days – default 30 days> after the outcome occurs. For patients who +have a dechallenge, we then determine whether it is a success (the +outcome stops) or a failure (the outcome continues). This is determined +by seeing whether the outcome starts within <decallenge evaluation +window days – default 30 days> after the exposure ends (outcome +starting is a dechallenge failure otherwise it is a success). For +patients who had a dechallenge, we then look at whether they have +another exposure (after decallenge evaluation window days from the first +exposure end), which is a rechallenge and this is classed as a failure +(if the outcome does not start during the rechallenge exposure era) and +a success (if the outcome does occur during the rechallenge exposure +era).

      +
      +

      Example Inputs +

      +

      Here we consider the inputs are:

      +
      +targetIds <- c(1)
+outcomeIds <- c(2) 
+dechallengeStopInterval <- 30
+dechallengeEvaluationWindow <- 31
      +
      +
      +

      Example Data Plot +

      +
      +Figure 3 - Example data for five patients with dates.
      Figure 3 - Example data for five patients with +dates.
      +
      +
      +
      +

      Example Data Table +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example dechallenge-rechallenge data with dates.
      patientIdcohortDefinitionIdcohortStartDatecohortEndDate
      112001-01-202001-01-25
      112001-10-202001-12-05
      212005-09-102005-09-15
      212006-03-042006-03-21
      212006-05-032006-05-05
      312004-04-022004-05-17
      412002-03-032002-06-12
      412003-02-012003-02-30
      412003-08-042003-08-24
      512005-02-012005-10-08
      512007-04-032007-05-03
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example time-to-event data with timing.
      patientIdcohortDefinitionIdcohortStartDatecohortEndDate
      121999-10-031999-10-08
      122001-10-302001-11-07
      322004-05-162004-05-18
      422002-06-032002-06-14
      422003-02-202003-03-01
      522006-07-212006-08-03
      522008-01-012008-01-09
      +

      Let’s consider ten patients in Table 5 and Table 6 with 30 days for +the dechallenge stop interval and 31 days for the decallenge evaluation +window. First, find all cases where the outcome occurs during any +exposure era and then the exposure ends within 30 days after the outcome +start. These are the dechallenges. Then investigate whether a new +outcome starts within 31 days of the exposure era ending. These are the +failed dechallenges, otherwise the dechallenge is a success. Next, for +the dechallenges, find any drug exposures that occur more than 31 days +after the dechallenge exposure era end. These are rechallaneges. For +each rechallenge, determine whether the outcome starts within 31 days of +the rechallenge exposure era start. If an outcome occurs, the +rechallenge is a success, otherwise it is a failure.

      +
      +
      +

      Intermediary Table +

      + + ++++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Dehcallenge-rechallenge summary table showing each dechallenge. +Only some patients with a dechallenge will have a rechallenge.
      patientIdoutcomeDateexposureEndoutcomeAfterfutureExposurefutureOutcomedechallengeTyperechallengeType
      12001-11-302001-12-05---Success-
      22006-03-102006-03-21-2006-05-03-SeccessSuccess
      32004-05-162004-05-172004-01-12--Fail-
      42002-06-032002-06-12-2003-01-012003-02-20SuccessFail
      +
      +
      +

      Intermediary Plots +

      +
      +Figure 4 - Example data for five patients with dechallenges highlighted and labelled.
      Figure 4 - Example data for five patients with +dechallenges highlighted and labelled.
      +
      +
      +Figure 5 - Example data for five patients with rechallenges highlighted and labelled.
      Figure 5 - Example data for five patients with +rechallenges highlighted and labelled.
      +
      +
      +
      +

      Summary +

      +

      We would then summarize the results by saying there were 4 +dechallenges, 3 of which were a success and 1 of which was a fail. 2 +patients had rechallenges with 1 being a fail and 1 being a success, see +Table 8 as the example output for one target and outcome.

      + + ++++++++ + + + + + + + + + + + + + + + + +
      Dehcallenge-rechallenge output.
      dechallengeAttemptsdechallengeSuccessdechallengeFailurerechallengeAttemptsrechallengeSuccessrechallangeFailure
      431211
      +

      Note: The way an outcome and exposure phenotype are +designed can make it impossible or unlikely to see a dechallenge fail. +For example, if an outcome is designed with a 365 day washout window, +then it means there cannot be another outcome occurring within 365 days +of another outcome. As a dechallange failure is the outcome occurring +within dechallenge evaluation window days after the exposure ends (and +the exposure must end within stop interval days of the outcome to be a +dechallenge), then using the defaults for these values means a +dechallenge failure requires an outcome to be possible within 60 days of +the dechallenge outcome, which is impossible with a 365 washout +window.

      +
      +
      +
      +
      +

      Aggregate Covariates +

      +
      +

      Inputs +

      +

      A vector of targetIds plus the minimum prior observation required for +the target cohorts and specifying which features to extract +(covariateSettings).

      +
      +
      +

      Outputs +

      +

      For each target cohort restricted to only the patients with minimum +prior observation at index and first occurrence the mean value for each +feature of interest is extracted into a data.frame.

      +
      +
      +

      Worked Example +

      +

      The aggregate covariates calculates the mean value of a feature +within a cohort of patients. In this analysis we restrict to first +occurrence in the cohort with a minimum prior observation in days +specified by the user (default 365 days). This restriction is +implemented as otherwise a patient could contribute multiple times to +the mean value and this makes interpretation difficult.

      +
      +

      Example Inputs +

      +

      Here we consider the inputs are:

      +
      +minPriorObservation <- 365
+covariateSettings <- FeatureExtraction::createCovariateSettings(
+  useDemographicsAge = T, 
+  useDemographicsGender = T,
+  useConditionOccurrenceAnyTimePrior = T, includedCovariateConceptIds = c(201820)
+  )
      +
      +
      +

      Example Data +

      +

      Let’s assumed we have two two cohorts (id 1 and 2) the first cohort +contains five patients who have >365 days prior observation at index +and the second contains three patients who have >365 days prior +observation at index.

      +

      The patients features’ are displayed in Table 7, containing patients’ +age at index, whether they have diabetes anytime prior to index and +their sex as features.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example patient level feature data.
      patientIdcohortIdfeaturevalue
      11age50
      11sexMale
      11diabetesYes
      21age18
      21sexFemale
      21diabetesNo
      31age22
      31sexMale
      31diabetesNo
      41age40
      41sexMale
      41diabetesNo
      51age70
      51sexFemale
      51diabetesYes
      12age24
      12sexFemale
      12diabetesNo
      22age35
      22sexFemale
      22diabetesNo
      32age31
      32sexFemale
      32diabetesNo
      +
      +
      +

      Results +

      +

      We calculate the mean values for each feature per cohort:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example aggregate features for two example cohorts.
      cohortIdfeaturemean
      1Age40.0
      1Sex: Male0.6
      1Diabetes: Yes0.4
      2Age30.0
      2Sex: Male0.0
      2Diabetes: Yes0.0
      +

      The database and cohort comparison implements the aggregate covariate +analysis for all target and outcome ids fed into characterization across +all OMOP CDM databases available and then lets users compare the mean +values of the features between databases for the same cohort or across +different cohorts within the same database. The standardized mean +different is calculated between two cohorts when possible, this is +calculated per feature as: abs(mean value in cohort 1 - mean value in +cohort 2)/((standard deviation of values in cohort 1 squared plus +standard deviation of values in cohort 2 squared)/2).

      +
      +
      +
      +
      +

      Risk Factor Analysis +

      +
      +

      Inputs +

      +

      A vector of targetIds and outcomeIds plus the minimum prior +observation required for the target cohorts, the outcome washout days +for the outcomes, settings for the time-at-risk and covariate settings +specifying which features to extract.

      +
      +
      +

      Outputs +

      +

      For each target and outcome combination we run aggregate covariate +analysis for the special case of comparing patients in cohort 1 +(patients in the target cohort for the first time with 365 days prior +observation who go on to have the first occurrence of the outcome in +washout days during some time-at-risk relative to the target cohort +index) vs cohort 2 (patients in the target cohort for the first time +with 365 days prior observation who do not go on to have the first +occurrence of the outcome in washout days during some time-at-risk +relative to the target cohort index).

      +
      +
      +

      Worked Example +

      +

      Lets consider an example with a time-at-risk of target cohort start + +1 to target cohort start + 180.

      +
      +

      Example Inputs +

      +
      +targetId <- 1
+outcomeId <- 2
+minPriorObservation <- 365
+outcomeWashoutDays <- 365
+riskWindowStart <- 1
+startAnchor <- 'cohort start'
+riskWindowEnd <- 180
+endAnchor <- 'cohort start'
+covariateSettings <- FeatureExtraction::createCovariateSettings(
+  useDemographicsAge = T, 
+  useDemographicsGender = T,
+  useConditionOccurrenceAnyTimePrior = T, includedCovariateConceptIds = c(201820)
+  )
      +
      +
      +

      Example Data +

      + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example target cohort.
      patientIdtargetCohortIdcohortStartDatecohortEndDateobservationStart
      112001-01-202001-01-252000-02-01
      112001-10-202001-12-052000-02-01
      212005-09-102005-09-152001-02-01
      312004-04-022004-05-172001-02-01
      412002-03-032002-06-122001-02-01
      412003-02-012003-02-302001-02-01
      412003-08-042003-08-242001-02-01
      512005-02-012005-10-082001-02-01
      512007-04-032007-05-032001-02-01
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example outcome cohort.
      patientIdtargetCohortIdcohortStartDatecohortEndDate
      121999-10-031999-10-08
      122001-10-302001-11-07
      322004-05-162004-05-18
      422002-06-032002-06-14
      422003-02-202003-03-01
      522006-07-212006-08-03
      522008-01-012008-01-09
      +
      +
      +

      Intermedeiary Tables +

      +

      First, we find the first target with 365 days prior obs. Patient 1 is +removed as they are exposed for the first time with less than 365 days +prior observation. Patients 4 and 5 non-first exposures are removed. +This leaves:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example target cohort meeting risk factor inclusion +criteria.
      patientIdtargetCohortIdcohortStartDatecohortEndDate
      212005-09-102005-09-15
      312004-04-022004-05-17
      412002-03-032002-06-12
      512005-02-012005-10-08
      +

      We then find the patients in the target cohort with the outcome and +no-outcome occurring during 1 day to 180 days after index:

      + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example target cohort meeting risk factor inclusion +criteria.
      patientIdtargetCohortIdcohortStartDatecohortEndDatelabels
      212005-09-102005-09-15Non-outcome
      312004-04-022004-05-17Outcome
      412002-03-032002-06-12Outcome
      512005-02-012005-10-08Non-outcome
      +

      Note: we also remove patients in the target who have +the outcome during outcome washout days prior to target index. In the +example, nobody had the outcome prior, so this was not observed.

      +

      If the features for these four patients are:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example patient level feature data.
      patientIdcohortIdfeaturevalue
      2Non-outcomeage50
      2Non-outcomesexMale
      2Non-outcomediabetesYes
      3Outcomeage18
      3OutcomesexFemale
      3OutcomediabetesNo
      4Outcomeage22
      4OutcomesexMale
      4OutcomediabetesNo
      5Non-outcomeage40
      5Non-outcomesexMale
      5Non-outcomediabetesNo
      +
      +
      +

      Results +

      +

      We calculate the mean values for each feature per non-outcome and +outcome cohort:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example aggregate features for risk factor analysis.
      cohortIdfeaturemean
      OutcomeAge20.0
      OutcomeSex: Male0.5
      OutcomeDiabetes: Yes0.0
      Non-outcomeAge45.0
      Non-outcomeSex: Male1.0
      Non-outcomeDiabetes: Yes0.5
      +

      We can then implement the standardized mean different calculated +between the outcome and non-outcome cohorts, this is calculated per +feature as: abs(mean value in outcome cohort - mean value in non-outcome +cohort)/((standard deviation of values in outcome cohort squared plus +standard deviation of values in non-outcome cohort squared)/2).

      +
      +
      +
      +
      +

      Case Series +

      +

      The cases series looks at the patients in a target cohort who have +the outcome during a specified time-at-risk and calculates the aggregate +covariates at three different time periods: shortly before index, +between target index and outcome index and shortly after outcome +index.

      +
      +

      Inputs +

      +

      A vector of targetIds and outcomeIds plus the minimum prior +observation required for the target cohorts, the outcome washout days +for the outcomes, settings for the time-at-risk and covariate settings +specifying which features to extract.

      +

      In addition you need to specify how long before target index to +extract before index features (preTargetIndexDays) and how long after +outcome index to extract after index features +(postOutcomeIndexDays).

      +
      +
      +

      Outputs +

      +

      For each target and outcome combination we run aggregate covariate +analysis patients in the target patients (with a minimum of prior +observation day before index) who have the outcome (for the first time +in outcome washout days). We use three different time periods for +feature extraction:

      +
        +
      • (before) preTargetIndexDays before target index up to target +index
        • +
      • (during) between target index plus 1 day to outcome index
        • +
      • (after) 1 day after outcome index to outcome index plus +postOutcomeIndexDays
        • +
      +
      +
      +

      Worked Example +

      +

      In this example we look at how often diabetes is recorded for the +cases (people with the target cohort who have the outcome within 180 +days of target index) in the year before target index, between target +index and outcome index and the 1 year after outcome index.

      +
      +

      Example Inputs +

      +

      Here we consider the inputs are:

      +
      +targetId <- 1
+outcomeId <- 2
+minPriorObservation <- 365
+outcomeWashoutDays <- 365
+preTargetIndexDays <- 365
+postOutcomeIndexDays <- 365
+riskWindowStart <- 1
+startAnchor <- 'cohort start'
+riskWindowEnd <- 180
+endAnchor <- 'cohort start'
+covariateSettings <- FeatureExtraction::createCovariateSettings(
+  useConditionOccurrenceAnyTimePrior = T, includedCovariateConceptIds = c(201820)
+  )
      +
      +
      +

      Example Data +

      + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example target cohort.
      patientIdtargetCohortIdcohortStartDatecohortEndDateobservationStart
      112001-01-202001-01-252000-02-01
      112001-10-202001-12-052000-02-01
      212005-09-102005-09-152001-02-01
      312004-04-022004-05-172001-02-01
      412002-03-032002-06-122001-02-01
      412003-02-012003-02-302001-02-01
      412003-08-042003-08-242001-02-01
      512005-02-012005-10-082001-02-01
      512007-04-032007-05-032001-02-01
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example outcome cohort.
      patientIdtargetCohortIdcohortStartDatecohortEndDate
      121999-10-031999-10-08
      122001-10-302001-11-07
      322004-05-162004-05-18
      422002-06-032002-06-14
      422003-02-202003-03-01
      522006-07-212006-08-03
      522008-01-012008-01-09
      +
      +
      +

      Intermedeiary Tables +

      +

      First, we find the first target with 365 days prior obs. Patient 1 is +removed as they are exposed for the first time with less than 365 days +prior observation. Patients 4 and 5 non-first exposures are removed. +This leaves:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example target cohort meeting risk factor inclusion +criteria.
      patientIdtargetCohortIdcohortStartDatecohortEndDate
      212005-09-102005-09-15
      312004-04-022004-05-17
      412002-03-032002-06-12
      512005-02-012005-10-08
      +

      We then find the patients in the target cohort with the outcome +occurring during 1 day to 180 days after index:

      + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example target cohort meeting case inclusion +criteria.
      patientIdtargetCohortIdcohortStartDatecohortEndDatelabels
      312004-04-022004-05-17Outcome
      412002-03-032002-06-12Outcome
      +

      Note: we also remove patients in the target who have +the outcome during outcome washout days prior to target index. In the +example, nobody had the outcome prior, so this was not observed.

      +

      Now we define the before( 365 days before target index up to target +index), between (target index plus 1 and outcome) and after (outcome +index plus 1 to outcome index plus 365):

      + + ++++++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example cases with before/during/after dates.
      patientIdtargetCohortIdtargetStartDateoutcomeStartDatebeforeStartDatebeforeEndDateduringStartDateduringEndDateafterStartDateafterEndDate
      312004-04-022004-05-162003-04-032004-04-022004-04-032004-05-162004-05-172005-05-16
      412002-03-032002-06-032001-03-032002-03-032002-03-042002-06-032002-06-042003-06-03
      +

      If the features for these two patients at the three time periods +are:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Example patient level case feature data.
      patientIdfeaturetimePeriodvalue
      3diabetesbeforeNo
      3diabetesduringNo
      3diabetesafterYes
      4diabetesbeforeYes
      4diabetesduringYes
      4diabetesafterYes
      +
      +
      +

      Results +

      +

      Finally, we aggregate over the time periods:

      + + + + + + + + + + + + + + + + + + + + + + + + +
      Example patient level case feature data.
      featuretimePeriodvalue
      diabetes: Yesbefore0.5
      diabetes: Yesduring0.5
      diabetes: Yesafter1.0
      +
      +
      +
      +
      + + + +
      + + + +
      +

      +

      Developed by Jenna Reps, Patrick Ryan, Chris Knoll.

      +
      + +
      +

      +

      Site built with pkgdown 2.0.7.

      +
      + +
      +
      + + + + + + + + diff --git a/docs/articles/UsingPackage.html b/docs/articles/UsingPackage.html index c62e6dd..0243455 100644 --- a/docs/articles/UsingPackage.html +++ b/docs/articles/UsingPackage.html @@ -6,7 +6,7 @@ Using Characterization Package • Characterization - + @@ -33,7 +33,7 @@ Characterization - 2.0.0 + 2.0.1.9000 @@ -61,6 +61,9 @@
    • Characterization Installation Guide
      • +
    • + Characterization Package Specification +
    • Using Characterization Package
      • @@ -72,7 +75,7 @@