Run self-controlled cohort — runSelfControlledCohort • SelfControlledCohort

runSelfControlledCohort generates population-level estimation by comparing exposed and unexposed time among exposed cohort.

runSelfControlledCohort(
  connectionDetails = NULL,
  cdmDatabaseSchema,
  connection = NULL,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  exposureIds = NULL,
  outcomeIds = NULL,
  negativeControlPairs = NULL,
  controlType = "outcome",
  exposureDatabaseSchema = cdmDatabaseSchema,
  exposureTable = "drug_era",
  outcomeDatabaseSchema = cdmDatabaseSchema,
  outcomeTable = "condition_era",
  firstExposureOnly = TRUE,
  firstOutcomeOnly = TRUE,
  minAge = "",
  maxAge = "",
  studyStartDate = "",
  studyEndDate = "",
  addLengthOfExposureExposed = TRUE,
  riskWindowStartExposed = 1,
  riskWindowEndExposed = 30,
  addLengthOfExposureUnexposed = TRUE,
  riskWindowEndUnexposed = -1,
  riskWindowStartUnexposed = -30,
  hasFullTimeAtRisk = FALSE,
  washoutPeriod = 0,
  followupPeriod = 0,
  computeThreads = getOption("strategus.SelfControlledCohort.computeThreads", default =
    parallel::detectCores() - 1),
  riskWindowsTable = "#risk_windows",
  resultsTable = "#results",
  keepResultsTables = TRUE,
  extractResults = TRUE,
  resultsDatabaseSchema = NULL,
  resultExportPath = "scc_result",
  databaseId,
  analysisId = 1,
  analysisDescription = paste("SCC analysis", analysisId),
  resultExportManager = getDefaultExportManager(resultExportPath, databaseId),
  runDiagnostics = TRUE,
  diagnostics = c("all"),
  diagnosticThresholds = getDefaultDiagnosticThresholds()
)

Arguments

connectionDetails: An R object of type connectionDetails created using the function createConnectionDetails in the DatabaseConnector package.
cdmDatabaseSchema: Name of database schema that contains the OMOP CDM and vocabulary.
connection: DatabaseConnector connection instance
tempEmulationSchema: Some database platforms like Oracle and Impala do not truly support temp tables. To emulate temp tables, provide a schema with write privileges where temp tables can be created.
exposureIds: A vector containing the drug_concept_ids or cohort_definition_ids of the exposures of interest. If empty, all exposures in the exposure table will be included.
outcomeIds: The condition_concept_ids or cohort_definition_ids of the outcomes of interest. If empty, all the outcomes in the outcome table will be included.
negativeControlPairs: A list of vectors for pairs of negative control
controlType: Calibrate effect estimates with outcome (default) or exposure controls
exposureDatabaseSchema: The name of the database schema that is the location where the exposure data used to define the exposure cohorts is available. If exposureTable = DRUG_ERA, exposureDatabaseSchema is not used by assumed to be cdmSchema. Requires read permissions to this database.
exposureTable: The tablename that contains the exposure cohorts. If exposureTable <> DRUG_ERA, then expectation is exposureTable has format of COHORT table: cohort_concept_id, SUBJECT_ID, COHORT_START_DATE, COHORT_END_DATE.
outcomeDatabaseSchema: The name of the database schema that is the location where the data used to define the outcome cohorts is available. If exposureTable = CONDITION_ERA, exposureDatabaseSchema is not used by assumed to be cdmSchema. Requires read permissions to this database.
outcomeTable: The tablename that contains the outcome cohorts. If outcomeTable <> CONDITION_OCCURRENCE, then expectation is outcomeTable has format of COHORT table: COHORT_DEFINITION_ID, SUBJECT_ID, COHORT_START_DATE, COHORT_END_DATE.
firstExposureOnly: If TRUE, only use first occurrence of each drug concept id for each person
firstOutcomeOnly: If TRUE, only use first occurrence of each condition concept id for each person.
minAge: Integer for minimum allowable age.
maxAge: Integer for maximum allowable age.
studyStartDate: Date for minimum allowable data for index exposure. Date format is 'yyyymmdd'.
studyEndDate: Date for maximum allowable data for index exposure. Date format is 'yyyymmdd'.
addLengthOfExposureExposed: If TRUE, use the duration from drugEraStart -> drugEraEnd as part of timeAtRisk.
riskWindowStartExposed: Integer of days to add to drugEraStart for start of timeAtRisk (0 to include index date, 1 to start the day after).
riskWindowEndExposed: Additional window to add to end of exposure period (if addLengthOfExposureExposed = TRUE, then add to exposure end date, else add to exposure start date).
addLengthOfExposureUnexposed: If TRUE, use the duration from exposure start -> exposure end as part of timeAtRisk looking back before exposure start.
riskWindowEndUnexposed: Integer of days to add to exposure start for end of timeAtRisk (0 to include index date, -1 to end the day before).
riskWindowStartUnexposed: Additional window to add to start of exposure period (if addLengthOfExposureUnexposed = TRUE, then add to exposure end date, else add to exposure start date).
hasFullTimeAtRisk: If TRUE, restrict to people who have full time-at-risk exposed and unexposed.
washoutPeriod: Integer to define required time observed before exposure start.
followupPeriod: Integer to define required time observed after exposure start.
computeThreads: Number of parallel threads for computing IRRs with exact confidence intervals.
riskWindowsTable: String: optionally store the risk windows in a (non-temporary) table.
resultsTable: String: optionally store the summary results (number exposed/ unexposed patients per outcome-exposure pair) in a (non-temporary) table. Note that this table does not store the rate ratios, only the values required to calculate rate ratios.
keepResultsTables: Keep the results tables in place if they exist. This allows the data set to be added to with aditional targets and outcomes. (ignored if temporary tables are used, default)
extractResults: Export results to disk. In the case of very large exposure/outcome set pairs it is often more ideal to create a permanent results table with the @resultsTable parameter and extract and calibrate small subsets on demand. Performing calibration across the full set of outcome/exposure pairs can take a significant amount of time. If set to false, no relative risk ratios will be produced.
resultsDatabaseSchema: Schema to oputput results to. Ignored if resultsTable and riskWindowsTable are temporary.
resultExportPath: Folder where result files are exported
databaseId: Unique identifier for database - required
analysisId: An integer unique to this analysis
analysisDescription: A string description of the analysis (optional)
resultExportManager: ResultModelManager::ResultExportManager instance - customize this to implement an alternative mechanism for exporting results
runDiagnostics: If TRUE, run diagnostic tests on the results
diagnostics: Character vector specifying which diagnostics to run. Options: "all", "counts", "event_dependent", "pre_exposure", "window_balance", "cohort_stability". Default is "all".
diagnosticThresholds: Named list of diagnostic thresholds. See getDefaultDiagnosticThresholds()

Value

An object of type sccResults containing the results of the analysis.

Details

Population-level estimation method that estimates incidence rate comparison of exposed/unexposed time within an exposed cohort. If multiple exposureIds and outcomeIds are provided, estimates will be generated for every combination of exposure and outcome.

References

Ryan PB, Schuemie MJ, Madigan D.Empirical performance of a self-controlled cohort method: lessons for developing a risk identification and analysis system. Drug Safety 36 Suppl1:S95-106, 2013

Examples

if (FALSE) { # \dontrun{
# Use Eunomia synthetic database for demonstration
connectionDetails <- Eunomia::getEunomiaConnectionDetails()

result <- runSelfControlledCohort(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = "main",
  exposureIds = c(1124300),
  outcomeIds = 444382,
  outcomeTable = "condition_era",
  databaseId = "Eunomia"
)
} # }