Added controlType argument to runSccsAnalyses()

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: SelfControlledCaseSeries
 Type: Package
 Title: Self-Controlled Case Series
-Version: 5.2.3
-Date: 2024-08-12
+Version: 5.3.0
+Date: 2024-08-13
 Authors@R: c(
   person("Martijn", "Schuemie", , "[email protected]", role = c("aut", "cre")),
 	person("Patrick", "Ryan", role = c("aut")),
@@ -19,7 +19,7 @@ Description: SelfControlledCaseSeries is an R package for performing self-
 	included at once (MSCCS), with regularization on all coefficients except for the
 	exposure of interest.
 VignetteBuilder: knitr
-URL:  https://ohdsi.github.io/SelfControlledCaseSeries, https://github.com/OHDSI/SelfControlledCaseSeries
+URL:  https://ohdsi.github.io/SelfControlledCaseSeries/, https://github.com/OHDSI/SelfControlledCaseSeries
 BugReports: https://github.com/OHDSI/SelfControlledCaseSeries/issues
 Depends:
 	R (>= 4.0.0),

NEWS.md

@@ -1,3 +1,11 @@
+SelfControlledCaseSeries 5.3.0
+==============================
+
+Changes
+
+1. Added `controlType` argument to `runSccsAnalyses()`, explicitly setting the type of (negative) controls: outcome controls or exposure controls. Setting to "outcome" (the default) will now group by exposure (and nesting cohort if defined).
+
+
 SelfControlledCaseSeries 5.2.3
 ==============================
 

R/RunAnalyses.R

@@ -160,6 +160,11 @@ createDefaultSccsMultiThreadingSettings <- function(maxCores) {
 #' @param sccsMultiThreadingSettings       An object of type `SccsMultiThreadingSettings` as created using
 #'                                         the [createSccsMultiThreadingSettings()] or
 #'                                         [createDefaultSccsMultiThreadingSettings()] functions.
+#' @param controlType                      Type of negative (and positive) controls. Can be "outcome" or
+#'                                         "exposure". When set to "outcome", controls with the
+#'                                         same exposure (and nesting cohort) are grouped together for
+#'                                         calibration. When set to "exposure", controls with the same
+#'                                         outcome are grouped together.
 #'
 #' @return
 #' A tibble describing for each exposure-outcome-analysisId combination where the intermediary and
@@ -183,7 +188,8 @@ runSccsAnalyses <- function(connectionDetails,
                             exposuresOutcomeList,
                             analysesToExclude = NULL,
                             combineDataFetchAcrossOutcomes = FALSE,
-                            sccsMultiThreadingSettings = createSccsMultiThreadingSettings()) {
+                            sccsMultiThreadingSettings = createSccsMultiThreadingSettings(),
+                            controlType = "outcome") {
   errorMessages <- checkmate::makeAssertCollection()
   if (is(connectionDetails, "connectionDetails")) {
     checkmate::assertClass(connectionDetails, "connectionDetails", add = errorMessages)
@@ -213,6 +219,7 @@ runSccsAnalyses <- function(connectionDetails,
   checkmate::assertDataFrame(analysesToExclude, null.ok = TRUE, add = errorMessages)
   checkmate::assertLogical(combineDataFetchAcrossOutcomes, len = 1, add = errorMessages)
   checkmate::assertClass(sccsMultiThreadingSettings, "SccsMultiThreadingSettings", add = errorMessages)
+  checkmate::assertChoice(controlType, c("outcome", "exposure"), add = errorMessages)
   checkmate::reportAssertions(collection = errorMessages)
 
   uniqueExposuresOutcomeList <- unique(lapply(lapply(lapply(exposuresOutcomeList, unlist), as.character), paste, collapse = " "))
@@ -445,7 +452,8 @@ runSccsAnalyses <- function(connectionDetails,
       exposuresOutcomeList = exposuresOutcomeList,
       outputFolder = outputFolder,
       mainFileName = mainFileName,
-      calibrationThreads = sccsMultiThreadingSettings$calibrationThreads
+      calibrationThreads = sccsMultiThreadingSettings$calibrationThreads,
+      controlType = controlType
     )
   }
 
@@ -825,7 +833,12 @@ createSccsModelObject <- function(params) {
   }
 }
 
-summarizeResults <- function(referenceTable, exposuresOutcomeList, outputFolder, mainFileName, calibrationThreads = 1) {
+summarizeResults <- function(referenceTable,
+                             exposuresOutcomeList,
+                             outputFolder,
+                             mainFileName,
+                             calibrationThreads = 1,
+                             controlType) {
   rows <- list()
   # i = 1
   pb <- txtProgressBar(style = 3)
@@ -875,6 +888,7 @@ summarizeResults <- function(referenceTable, exposuresOutcomeList, outputFolder,
           }
           row <- tibble(
             exposuresOutcomeSetId = refRow$exposuresOutcomeSetId,
+            nestingCohortId = refRow$nestingCohortId,
             outcomeId = refRow$outcomeId,
             analysisId = refRow$analysisId,
             covariateAnalysisId = covariateSettings$covariateAnalysisId,
@@ -909,18 +923,22 @@ summarizeResults <- function(referenceTable, exposuresOutcomeList, outputFolder,
   mainResults <- bind_rows(rows)
   mainResults <- calibrateEstimates(
     results = mainResults,
-    calibrationThreads = calibrationThreads
+    calibrationThreads = calibrationThreads,
+    controlType = controlType
   )
   saveRDS(mainResults, mainFileName)
 }
 
-calibrateEstimates <- function(results, calibrationThreads) {
+calibrateEstimates <- function(results, calibrationThreads, controlType) {
   if (nrow(results) == 0) {
     return(results)
   }
   message("Calibrating estimates")
-  groups <- split(results, paste(results$covariateId, results$analysisId))
-
+  if (controlType == "outcome") {
+    groups <- split(results, paste(results$eraId, results$nestingCohortId, results$covariateId, results$analysisId))
+  } else {
+    groups <- split(results, paste(results$outcomeId, results$covariateId, results$analysisId))
+  }
   cluster <- ParallelLogger::makeCluster(min(length(groups), calibrationThreads))
   results <- ParallelLogger::clusterApply(cluster, groups, calibrateGroup)
   ParallelLogger::stopCluster(cluster)

vignettes/MultipleAnalyses.Rmd

@@ -325,13 +325,14 @@ referenceTable <- runSccsAnalyses(
   combineDataFetchAcrossOutcomes = TRUE,
   exposuresOutcomeList = exposuresOutcomeList,
   sccsAnalysisList = sccsAnalysisList,
-  sccsMultiThreadingSettings = multiThreadingSettings
+  sccsMultiThreadingSettings = multiThreadingSettings,
+  controlType = "exposure"
 )
 ```
 
 In the code above, we first specify how many parallel threads `SelfControlledCaseSeries` can use. Many of the computations can be computed in parallel, and providing more than one CPU core can greatly speed up the computation. Here we specify `SelfControlledCaseSeries` can use all but one of the CPU cores detected in the system (using the `parallel::detectCores()` function). 
 
-We call `runSccsAnalyses`, providing the arguments for connecting to the database, which schemas and tables to use, as well as the analyses and hypotheses of interest. The `outputFolder` specifies where the outcome models and intermediate files will be written. 
+We call `runSccsAnalyses`, providing the arguments for connecting to the database, which schemas and tables to use, as well as the analyses and hypotheses of interest. The `outputFolder` specifies where the outcome models and intermediate files will be written. Because in this example we use negative control exposures, we must explicitly specify `controlType = "exposure"`. This will cause the different negative control exposure-outcome pairs to be used for the same outcome.
 
 ## Restarting