vignettes/UsingPackage.Rmd
UsingPackage.RmdThis vignette describes how you can use the Characterization package for various descriptive studies using OMOP CDM data. The Characterization package currently contains three different types of analyses:
In this vignette we will show working examples using the
Eunomia R package that contains simulated data. Run the
following code to install the Eunomia R package:
install.packages("remotes")
remotes::install_github("ohdsi/Eunomia")Eunomia can be used to create a temporary SQLITE database with the
simulated data. The function getEunomiaConnectionDetails
creates a SQLITE connection to a temporary location. The function
createCohorts then populates the temporary SQLITE database
with the simulated data ready to be used.
connectionDetails <- Eunomia::getEunomiaConnectionDetails()
Eunomia::createCohorts(connectionDetails = connectionDetails)## Connecting using SQLite driver## Creating cohort: Celecoxib
##
|
| | 0%
|
|======================================================================| 100%## Executing SQL took 0.00523 secs## Creating cohort: Diclofenac
##
|
| | 0%
|
|======================================================================| 100%## Executing SQL took 0.00508 secs## Creating cohort: GiBleed
##
|
| | 0%
|
|======================================================================| 100%## Executing SQL took 0.00888 secs## Creating cohort: NSAIDs
##
|
| | 0%
|
|======================================================================| 100%## Executing SQL took 0.0484 secs## Cohorts created in table main.cohort## cohortId name
## 1 1 Celecoxib
## 2 2 Diclofenac
## 3 3 GiBleed
## 4 4 NSAIDs
## description
## 1 A simplified cohort definition for new users of celecoxib, designed specifically for Eunomia.
## 2 A simplified cohort definition for new users ofdiclofenac, designed specifically for Eunomia.
## 3 A simplified cohort definition for gastrointestinal bleeding, designed specifically for Eunomia.
## 4 A simplified cohort definition for new users of NSAIDs, designed specifically for Eunomia.
## count
## 1 1844
## 2 850
## 3 479
## 4 2694We also need to have the Characterization package installed and loaded
remotes::install_github("ohdsi/FeatureExtraction")
remotes::install_github("ohdsi/Characterization", ref = "new_approach")##
## Attaching package: 'dplyr'## The following objects are masked from 'package:stats':
##
## filter, lag## The following objects are masked from 'package:base':
##
## intersect, setdiff, setequal, unionTo run an ‘Aggregate Covariate’ analysis you need to create a setting
object using createAggregateCovariateSettings. This
requires specifying:
FeatureExtraction::createCovariateSettings or by creating
your own custom feature extraction code.Using the Eunomia data were we previous generated four cohorts, we can use cohort ids 1,2 and 4 as the targetIds and cohort id 3 as the outcomeIds:
exampleTargetIds <- c(1, 2, 4)
exampleOutcomeIds <- 3If we want to get information on the sex, age at index and Charlson
Comorbidity index we can create the settings using
FeatureExtraction::createCovariateSettings:
exampleCovariateSettings <- FeatureExtraction::createCovariateSettings(
useDemographicsGender = T,
useDemographicsAge = T,
useCharlsonIndex = T
)There is an additional covariate setting require that is calculated
for the cases (patients in the target cohort with have the outcome
during the time-at-risk). This is called caseCovariateSettings and
should be created using the createDuringCovariateSettings function. The
user can pick conditions, drugs, measurements, procedures and
observations. In this example, we just include condition eras groups by
vocabulary heirarchy. We also need to specify two related variables
casePreTargetDuration which is the number of days before
target index to extract features for the cases (answers what happens
shortly before the target index) and
casePostOutcomeDuration which is the number of days after
the outcome date to extract features for the cases (answers what happens
after the outcome). The case covariates are also extracted between
target index and outcome (answers the question what happens during
target exposure).
caseCovariateSettings <- Characterization::createDuringCovariateSettings(
useConditionGroupEraDuring = T
)If we want to create the aggregate features for all our target cohorts, our outcome cohort and each target cohort restricted to those with a record of the outcome 1 day after target cohort start date until 365 days after target cohort end date with a outcome washout of 9999 (meaning we only include outcomes that are the first occurrence in the past 9999 days) and only include targets or outcomes where the patient was observed for 365 days or more prior, we can run:
exampleAggregateCovariateSettings <- createAggregateCovariateSettings(
targetIds = exampleTargetIds,
outcomeIds = exampleOutcomeIds,
riskWindowStart = 1, startAnchor = "cohort start",
riskWindowEnd = 365, endAnchor = "cohort start",
outcomeWashoutDays = 9999,
minPriorObservation = 365,
covariateSettings = exampleCovariateSettings,
caseCovariateSettings = caseCovariateSettings,
casePreTargetDuration = 90,
casePostOutcomeDuration = 90
)Next we need to use the
exampleAggregateCovariateSettings as the settings to
computeAggregateCovariateAnalyses, we need to use the
Eunomia connectionDetails and in Eunomia the OMOP CDM data and cohort
table are in the ‘main’ schema. The cohort table name is ‘cohort’. The
following code will apply the aggregated covariates analysis using the
previously specified settings on the simulated Eunomia data, but we can
specify the minCharacterizationMean to exclude covarites
with mean values below 0.01, and we must specify the
outputFolder where the csv results will be written to.
runCharacterizationAnalyses(
connectionDetails = connectionDetails,
cdmDatabaseSchema = "main",
targetDatabaseSchema = "main",
targetTable = "cohort",
outcomeDatabaseSchema = "main",
outcomeTable = "cohort",
characterizationSettings = createCharacterizationSettings(
aggregateCovariateSettings = exampleAggregateCovariateSettings
),
databaseId = "Eunomia",
runId = 1,
minCharacterizationMean = 0.01,
outputDirectory = file.path(getwd(), "example_char", "results"), executionPath = file.path(getwd(), "example_char", "execution"),
minCellCount = 10,
incremental = F,
threads = 1
)You can then see the results in the location
file.path(getwd(), 'example_char', 'results') where you
will find csv files.
To run a ‘Dechallenge Rechallenge’ analysis you need to create a
setting object using createDechallengeRechallengeSettings.
This requires specifying:
Using the Eunomia data were we previous generated four cohorts, we can use cohort ids 1,2 and 4 as the targetIds and cohort id 3 as the outcomeIds:
exampleTargetIds <- c(1, 2, 4)
exampleOutcomeIds <- 3If we want to create the dechallenge rechallenge for all our target cohorts and our outcome cohort with a 30 day dechallengeStopInterval and 31 day dechallengeEvaluationWindow:
exampleDechallengeRechallengeSettings <- createDechallengeRechallengeSettings(
targetIds = exampleTargetIds,
outcomeIds = exampleOutcomeIds,
dechallengeStopInterval = 30,
dechallengeEvaluationWindow = 31
)We can then run the analysis on the Eunomia data using
computeDechallengeRechallengeAnalyses and the settings
previously specified, with minCellCount removing values
less than the specified value:
dc <- computeDechallengeRechallengeAnalyses(
connectionDetails = connectionDetails,
targetDatabaseSchema = "main",
targetTable = "cohort",
settings = exampleDechallengeRechallengeSettings,
databaseId = "Eunomia",
outcomeTable = file.path(getwd(), "example_char", "results"),
minCellCount = 5
)Next it is possible to compute the failed rechallenge cases
failed <- computeRechallengeFailCaseSeriesAnalyses(
connectionDetails = connectionDetails,
targetDatabaseSchema = "main",
targetTable = "cohort",
settings = exampleDechallengeRechallengeSettings,
outcomeDatabaseSchema = "main",
outcomeTable = "cohort",
databaseId = "Eunomia",
outcomeTable = file.path(getwd(), "example_char", "results"),
minCellCount = 5
)To run a ‘Time-to-event’ analysis you need to create a setting object
using createTimeToEventSettings. This requires
specifying:
exampleTimeToEventSettings <- createTimeToEventSettings(
targetIds = exampleTargetIds,
outcomeIds = exampleOutcomeIds
)We can then run the analysis on the Eunomia data using
computeTimeToEventAnalyses and the settings previously
specified:
tte <- computeTimeToEventAnalyses(
connectionDetails = connectionDetails,
cdmDatabaseSchema = "main",
targetDatabaseSchema = "main",
targetTable = "cohort",
settings = exampleTimeToEventSettings,
databaseId = "Eunomia",
outcomeTable = file.path(getwd(), "example_char", "results"),
minCellCount = 5
)If you want to run multiple analyses (of the three previously shown)
you can use createCharacterizationSettings. You need to
input a list of each of the settings (or NULL if you do not want to run
one type of analysis). To run all the analyses previously shown in one
function:
characterizationSettings <- createCharacterizationSettings(
timeToEventSettings = list(
exampleTimeToEventSettings
),
dechallengeRechallengeSettings = list(
exampleDechallengeRechallengeSettings
),
aggregateCovariateSettings = exampleAggregateCovariateSettings
)
# save the settings using
saveCharacterizationSettings(
settings = characterizationSettings,
saveDirectory = file.path(tempdir(), "saveSettings")
)
# the settings can be loaded
characterizationSettings <- loadCharacterizationSettings(
saveDirectory = file.path(tempdir(), "saveSettings")
)
runCharacterizationAnalyses(
connectionDetails = connectionDetails,
cdmDatabaseSchema = "main",
targetDatabaseSchema = "main",
targetTable = "cohort",
outcomeDatabaseSchema = "main",
outcomeTable = "cohort",
characterizationSettings = characterizationSettings,
outputDirectory = file.path(tempdir(), "example", "results"),
executionPath = file.path(tempdir(), "example", "execution"),
csvFilePrefix = "c_",
databaseId = "1",
incremental = F,
minCharacterizationMean = 0.01,
minCellCount = 5
)This will create csv files with the results in the saveDirectory. You can run the following code to view the results in a shiny app:
viewCharacterization(
resultFolder = file.path(tempdir(), "example", "results"),
cohortDefinitionSet = NULL
)