SelfControlledCaseSeries: Self-Controlled Case Series

Description

Execute the self-controlled case series (SCCS) design using observational data in the OMOP Common Data Model. Extracts all necessary data from the database and transforms it to the format required for SCCS. Age and season can be modeled using splines assuming constant hazard within calendar months. Event-dependent censoring of the observation period can be corrected for. Many exposures can be included at once (MSCCS), with regularization on all coefficients except for the exposure of interest. Includes diagnostics for all major assumptions of the SCCS.

Author(s)

Maintainer: Martijn Schuemie schuemie@ohdsi.org

Authors:

• Patrick Ryan

• Trevor Shaddox

• Marc Suchard

See Also

Useful links:

• https://ohdsi.github.io/SelfControlledCaseSeries/

• https://github.com/OHDSI/SelfControlledCaseSeries

• Report bugs at https://github.com/OHDSI/SelfControlledCaseSeries/issues

SCCS Data

Description

SccsData is an S4 class that inherits from Andromeda. It contains information on the cases and their covariates.

A SccsData is typically created using getDbSccsData(), can only be saved using saveSccsData(), and loaded using loadSccsData().

Usage

## S4 method for signature 'SccsData'
show(object)

## S4 method for signature 'SccsData'
summary(object)

Arguments

SCCS Interval Data

Description

SccsIntervalData' is an S4 class that inherits from Andromeda. It contains information on the cases and their covariates, divided in non-overlapping time intervals.

A SccsIntervalData is typically created using createSccsIntervalData(), can only be saved using saveSccsIntervalData(), and loaded using loadSccsIntervalData().

Usage

## S4 method for signature 'SccsIntervalData'
show(object)

## S4 method for signature 'SccsIntervalData'
summary(object)

Arguments

Check diagnostic for event-dependent exposure

Description

This diagnostic tests whether there is a dependency between the event and subsequent exposures. This requires you have indicated one of the era covariates to be a pre-exposure window. This function simply checks whether the confidence interval for the effect estimate of that pre- exposure window overlaps with the nullBounds.

To designate an era covariate to be the pre-exposure window, set preExposure = TRUE when calling createEraCovariateSettings(). Note that, by default, preExposure will be TRUE if start is smaller than 0.

Usage

checkEventExposureIndependenceAssumption(sccsModel, nullBounds = c(0.8, 1.25))

Arguments

Value

A tibble with one row per pre-exposure window and four columns: ratio indicates the estimates incidence rate ratio for the pre-exposure window. lb and ub represent the upper and lower bounds of the 95 percent confidence interval, and pass is TRUE if the confidence interval intersects the null bounds.

Check diagnostic for event-dependent observation end

Description

This diagnostic tests whether there is a dependency between the event and the end of observation. It does so by adding a probe window at the end of observation, and checking whether the rate of the outcome is elevated (or decreased) during this window.

The end of observation probe window will automatically be added to the model by the createSccsIntervalData() function, unless the endOfObservationEraLength argument is set to 0. This function extracts the estimate for that window from the model, and compares it to the nullBounds.#'

Usage

checkEventObservationIndependenceAssumption(sccsModel, nullBounds = c(0.5, 2))

Arguments

Value

A tibble with one row and four columns: ratio indicates the estimates incidence rate ratio for the probe at the end of observation. lb and ub represent the upper and lower bounds of the 95 percent confidence interval, and pass is TRUE if the confidence interval intersects the null bounds.

Check if rare outcome assumption is violated

Description

Check if rare outcome assumption is violated

Usage

checkRareOutcomeAssumption(
  studyPopulation,
  firstOutcomeOnly = NULL,
  maxPrevalence = 0.1
)

Arguments

Details

Most SCCS analyses restrict to the first outcome occurrence per person to avoid violating the assumption that subsequent occurrences are independent. This is fine, as long as the outcome is rare. According to Farrington et al., the magnitude of the bias from violating this assumption is 0.5p, where p is the prevalence. By default we set the threshold for p at 0.1, corresponding to at most 5 percent bias.

The prevalence was computed in the getDbSccsData() function, within the population defined by the observation_period table, and restricted to the study period(s) and nesting cohort if used.

Value

A tibble with one row and three columns: outcomeProportion indicates the proportion of people having the outcome at least once. firstOutcomeOnly indicated whether the analysis was restricted to the first outcome only. rare is TRUE if the rare outcome assumption is met, or the analysis was not restricted to the first outcome.

References

Farrington P, Whitaker H, Ghebremichael-Weldeselassie Y, Self-Controlled Case Series Studies: A Modelling Guide with R, CRC Press, 2018

Check stability of outcome rate over time

Description

Check stability of outcome rate over time

Usage

checkTimeStabilityAssumption(
  studyPopulation,
  sccsModel = NULL,
  maxRatio = 1.1,
  alpha = 0.05
)

Arguments

Details

Computes for each month the observed and expected count, and computes the (weighted) mean ratio between the two. If splines are used to adjust for seasonality and/or calendar time, these adjustments are taken into consideration when considering the expected count. A one-sided p-value is computed against the null hypothesis that the ratio is smaller than maxRatio. If this p-value exceeds the specified alpha value, the series is considered stable.

Value

A tibble with one row and three columns: ratio indicates the estimated mean ratio between observed and expected. p is the p-value against the null-hypothesis that the ratio is smaller than maxRatio, and pass is TRUE if p is greater than alpha.

Compute the minimum detectable relative risk

Description

Compute the minimum detectable relative risk

Usage

computeMdrr(
  object,
  exposureCovariateId,
  alpha = 0.05,
  power = 0.8,
  twoSided = TRUE,
  method = "SRL1"
)

Arguments

Details

Compute the minimum detectable relative risk (MDRR) for a given study population, using the observed time at risk and total time in days and number of events. Five sample size formulas are implemented: sampling proportion, binomial proportion, 2 signed root likelihood ratio methods, and likelihood extension for age effects. The expressions by Musonda (2006) are used.

Value

A data frame with the MDRR, number of events, time at risk, and total time.

References

Musonda P, Farrington CP, Whitaker HJ (2006) Samples sizes for self-controlled case series studies, Statistics in Medicine, 15;25(15):2618-31

Compute P for pre-exposure risk gain

Description

This function is deprecated. Use computePreExposureGain() instead.

Usage

computePreExposureGainP(sccsData, studyPopulation, exposureEraId = NULL)

Arguments

Value

A one-sided p-value for whether the rate before exposure is higher than after, against the null of no change.#'

Check stability of outcome rate over time

Description

Check stability of outcome rate over time

Usage

computeTimeStability(
  studyPopulation,
  sccsModel = NULL,
  maxRatio = 1.1,
  alpha = 0.05
)

Arguments

Details

DEPRECATED. Use checkTimeStabilityAssumption() instead.

Value

A tibble with one row and three columns: ratio indicates the estimated mean ratio between observed and expected. p is the p-value against the null-hypothesis that the ratio is smaller than maxRatio, and pass is TRUE if p is greater than alpha.

Convert JSON to SccsAnalysesSpecifications

Description

Convert JSON to SccsAnalysesSpecifications

Usage

convertJsonToSccsAnalysesSpecifications(json)

Arguments

Value

An object of type SccsAnalysesSpecifications.

Convert SccsAnalysesSpecifications to JSON

Description

Convert SccsAnalysesSpecifications to JSON

Usage

convertSccsAnalysesSpecificationsToJson(sccsAnalysesSpecifications)

Arguments

Value

A string containing the JSON representation.

Convert untyped list to SccsAnalysesSpecifications

Description

Convert untyped list to SccsAnalysesSpecifications

Usage

convertUntypedListToSccsAnalysesSpecifications(untypedList)

Arguments

Value

An object of type SccsAnalysesSpecifications.

Create age covariate sesettings#' Create age covariate settings

Description

Create age covariate sesettings#' Create age covariate settings

Usage

createAgeCovariateSettings(
  ageKnots = 5,
  allowRegularization = FALSE,
  computeConfidenceIntervals = FALSE
)

Arguments

Details

Create an object specifying whether and how age should be included in the model. Age can be included by splitting patient time into calendar months. During a month, the relative risk attributed to age is assumed to be constant, and the risk from month to month is modeled using a quadratic spline.

Value

An object of type AgeCovariateSettings.

Create calendar time settings

Description

Create calendar time settings

Usage

createCalendarTimeCovariateSettings(
  calendarTimeKnots = 5,
  allowRegularization = FALSE,
  computeConfidenceIntervals = FALSE
)

Arguments

Details

Create an object specifying whether and how calendar time should be included in the model. Calendar time can be included by splitting patient time into calendar months. During a month, the relative risk attributed to calendar time is assumed to be constant, and the risk from month to month is modeled using a quadratic spline.

Whereas the seasonality covariate uses a cyclic spline, repeating every year, this calendar time covariate can model trends over years.

If a number of knots is specified, knots are automatically spaced according to equal percentiles of the data (people observed). If more than one study period is provided, two more knots (start and end) are automatically added for each additional study period. So if calendarTimeKnots = 5 and there are 3 study periods, the total number of knots will be 5 + 2 * (3 - 1) = 9.#'

Value

An object of type CalendarTimeCovariateSettings.

Create control interval settings

Description

Create control interval settings

Usage

createControlIntervalSettings(
  includeEraIds = NULL,
  excludeEraIds = NULL,
  start = 0,
  startAnchor = "era start",
  end = 0,
  endAnchor = "era end",
  firstOccurrenceOnly = FALSE
)

Arguments

Details

Create an object specifying how to create a control interval for the self-controlled risk interval (SCRI) design.

Value

An object of type ControlIntervalSettings.

Create a parameter object for the createSccsIntervalData() function

Description

Create a parameter object for the createSccsIntervalData() function

Usage

createCreateSccsIntervalDataArgs(
  eraCovariateSettings,
  ageCovariateSettings = NULL,
  seasonalityCovariateSettings = NULL,
  calendarTimeCovariateSettings = NULL,
  minCasesForTimeCovariates = 10000,
  endOfObservationEraLength = 30,
  eventDependentObservation = FALSE
)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type CreateSccsIntervalDataArgs.

References

Farrington, C. P., Anaya-Izquierdo, A., Whitaker, H. J., Hocine, M.N., Douglas, I., and Smeeth, L. (2011). Self-Controlled case series analysis with event-dependent observation periods. Journal of the American Statistical Association 106 (494), 417-426

Create a parameter object for the createScriIntervalData() function

Description

Create a parameter object for the createScriIntervalData() function

Usage

createCreateScriIntervalDataArgs(eraCovariateSettings, controlIntervalSettings)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type CreateScriIntervalDataArgs.

Create a parameter object for the createStudyPopulation() function

Description

Create a parameter object for the createStudyPopulation() function

Usage

createCreateStudyPopulationArgs(
  firstOutcomeOnly = FALSE,
  naivePeriod = 0,
  minAge = NULL,
  maxAge = NULL,
  genderConceptIds = NULL,
  restrictTimeToEraId = NULL
)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type CreateStudyPopulationArgs.

Create default SelfControlledCaseSeries multi-threading settings

Description

Create SelfControlledCaseSeries multi-threading settings based on the maximum number of cores to be used.

Usage

createDefaultSccsMultiThreadingSettings(maxCores)

Arguments

Value

An object of type SccsMultiThreadingSettings.

See Also

createSccsMultiThreadingSettings()

Examples

settings <- createDefaultSccsMultiThreadingSettings(10)

Create era covariate settings

Description

Create era covariate settings

Usage

createEraCovariateSettings(
  includeEraIds,
  excludeEraIds = NULL,
  label = "Covariates",
  stratifyById = FALSE,
  start = 0,
  startAnchor = "era start",
  end = 0,
  endAnchor = "era end",
  firstOccurrenceOnly = FALSE,
  allowRegularization = FALSE,
  profileLikelihood = FALSE,
  exposureOfInterest = FALSE,
  preExposure = start < 0
)

Arguments

Details

Create an object specifying how to create a (set of) era-based covariates.

Value

An object of type EraCovariateSettings.

Create exposure definition

Description

Create exposure definition

Usage

createExposure(exposureId, exposureIdRef = "exposureId", trueEffectSize = NA)

Arguments

Details

Create an exposure definition, to be used with the createExposuresOutcome function.

Value

An object of type Exposure.

Create a exposures-outcome combination.

Description

Create a exposures-outcome combination.

Usage

createExposuresOutcome(outcomeId, exposures, nestingCohortId = NULL)

Arguments

Details

Create a set of hypotheses of interest, to be used with the runSccsAnalyses() function.

Value

An object of type ExposuresOutcome.

Create a parameter object for the function fitSccsModel

Description

Create a parameter object for the function fitSccsModel

Usage

createFitSccsModelArgs(
  prior = createPrior("laplace", useCrossValidation = TRUE),
  control = createControl(cvType = "auto", selectorType = "byPid", startingVariance =
    0.1, seed = 1, resetCoefficients = TRUE, noiseLevel = "quiet"),
  profileGrid = NULL,
  profileBounds = c(log(0.1), log(10))
)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type FitSccsModelArgs.

Create a parameter object for the function getDbSccsData

Description

Create a parameter object for the function getDbSccsData

Usage

createGetDbSccsDataArgs(
  nestingCohortId = NULL,
  deleteCovariatesSmallCount = 0,
  studyStartDates = c(),
  studyEndDates = c(),
  maxCasesPerOutcome = 0,
  exposureIds = "exposureId",
  customCovariateIds = NULL
)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type GetDbSccsDataArgs.

Create the results data model tables on a database server.

Description

Create the results data model tables on a database server.

Usage

createResultsDataModel(
  connectionDetails = NULL,
  databaseSchema,
  tablePrefix = ""
)

Arguments

Details

Only PostgreSQL and SQLite servers are supported.

Create full SCCS analysis specifications

Description

Create full SCCS analysis specifications

Usage

createSccsAnalysesSpecifications(
  sccsAnalysisList,
  exposuresOutcomeList,
  analysesToExclude = NULL,
  combineDataFetchAcrossOutcomes = FALSE,
  sccsDiagnosticThresholds = SelfControlledCaseSeries::createSccsDiagnosticThresholds(),
  controlType = "outcome"
)

Arguments

Details

Analyses to Exclude

Normally, runSccsAnalyses will run all combinations of exposures-outcome-analyses settings. However, sometimes we may not need all those combinations. Using the analysesToExclude argument, we can remove certain items from the full matrix. This argument should be a data frame with at least one of the following columns:

• exposureId

• outcomeId

• nestingCohortId

• analysisId

This data frame will be joined to the outcome model reference table before executing, and matching rows will be removed. For example, if one specifies only one exposure ID and analysis ID, then any analyses with that exposure and that analysis ID will be skipped.

Value

An object of type SccsAnalysesSpecifications.

Create a SelfControlledCaseSeries analysis specification

Description

Create a SelfControlledCaseSeries analysis specification

Usage

createSccsAnalysis(
  analysisId = 1,
  description = "",
  getDbSccsDataArgs,
  createStudyPopulationArgs,
  createIntervalDataArgs,
  fitSccsModelArgs
)

Arguments

Value

An object of type SccsAnalysis, to be used with the runSccsAnalyses function.

Create SCCS diagnostics thresholds

Description

Threshold used when calling runSccsAnalyses() to determine if we pass or fail diagnostics.

Usage

createSccsDiagnosticThresholds(
  mdrrThreshold = 10,
  easeThreshold = 0.25,
  timeTrendMaxRatio = 1.1,
  rareOutcomeMaxPrevalence = 0.1,
  eventObservationDependenceNullBounds = c(0.5, 2),
  eventExposureDependenceNullBounds = c(0.8, 1.25)
)

Arguments

Value

An object of type SccsDiagnosticThresholds.

Create SCCS era data

Description

Create SCCS era data

Usage

createSccsIntervalData(studyPopulation, sccsData, createSccsIntervalDataArgs)

Arguments

Details

This function creates covariates based on the data in the sccsData argument, according to the provided settings. It chops patient time into periods during which all covariates remain constant. The output details these periods, their durations, and a sparse representation of the covariate values.

Value

An object of type SccsIntervalData.

Create SelfControlledCaseSeries multi-threading settings

Description

Create SelfControlledCaseSeries multi-threading settings

Usage

createSccsMultiThreadingSettings(
  getDbSccsDataThreads = 1,
  createStudyPopulationThreads = 1,
  createIntervalDataThreads = 1,
  fitSccsModelThreads = 1,
  cvThreads = 1,
  calibrationThreads = 1
)

Arguments

Value

An object of type SccsMultiThreadingSettings.

See Also

createDefaultSccsMultiThreadingSettings()

Create SCCS simulation settings

Description

Create SCCS simulation settings

Usage

createSccsSimulationSettings(
  meanPatientTime = 4 * 365,
  sdPatientTime = 2 * 365,
  minAge = 18 * 365,
  maxAge = 65 * 365,
  minBaselineRate = 0.001,
  maxBaselineRate = 0.01,
  minCalendarTime = as.Date("2000-01-01"),
  maxCalendarTime = as.Date("2010-01-01"),
  eraIds = c(1, 2),
  patientUsages = c(0.2, 0.1),
  usageRate = c(0.01, 0.01),
  usageRateSlope = c(0, 0),
  meanPrescriptionDurations = c(14, 30),
  sdPrescriptionDurations = c(7, 14),
  simulationRiskWindows = list(createSimulationRiskWindow(relativeRisks = 1),
    createSimulationRiskWindow(relativeRisks = 1.5)),
  includeAgeEffect = TRUE,
  ageKnots = 5,
  includeSeasonality = TRUE,
  seasonKnots = 5,
  includeCalendarTimeEffect = TRUE,
  calendarTimeKnots = 5,
  calendarTimeMonotonic = FALSE,
  outcomeId = 10
)

Arguments

Details

Create an object of settings for an SCCS simulation.

Value

An object of type SccsSimulationSettings.

Create Self-Controlled Risk Interval (SCRI) era data

Description

Create Self-Controlled Risk Interval (SCRI) era data

Usage

createScriIntervalData(studyPopulation, sccsData, createScriIntervalDataArgs)

Arguments

Details

This function creates interval data according to the elf-Controlled Risk Interval (SCRI) design. Unlike the generic SCCS design, where all patient time is used to establish a background rate, in the SCRI design a specific control interval (relative to the exposure) needs to be defined. The final model will only include time that is either part of the risk interval (defined using the eraCovariateSettings argument, or the control interval (defined using controlIntervalSettings).

Value

An object of type SccsIntervalData.

References

Greene SK, Kulldorff M, Lewis EM, Li R, Yin R, Weintraub ES, Fireman BH, Lieu TA, Nordin JD, Glanz JM, Baxter R, Jacobsen SJ, Broder KR, Lee GM. Near real-time surveillance for influenza vaccine safety: proof-of-concept in the Vaccine Safety Datalink Project. Am J Epidemiol. 2010 Jan 15;171(2):177-88. doi: 10.1093/aje/kwp345.

Create seasonality settings

Description

Create seasonality settings

Usage

createSeasonalityCovariateSettings(
  seasonKnots = 5,
  allowRegularization = FALSE,
  computeConfidenceIntervals = FALSE
)

Arguments

Details

Create an object specifying whether and how seasonality should be included in the model. Seasonality can be included by splitting patient time into calendar months. During a month, the relative risk attributed to season is assumed to be constant, and the risk from month to month is modeled using a cyclic quadratic spline.

Value

An object of type SeasonalityCovariateSettings.

Create a risk window definition for simulation

Description

Create a risk window definition for simulation

Usage

createSimulationRiskWindow(
  start = 0,
  end = 0,
  endAnchor = "era end",
  splitPoints = c(),
  relativeRisks = c(0)
)

Arguments

Value

An object of type SimulationRiskWindow.

Create a study population

Description

Create a study population

Usage

createStudyPopulation(sccsData, outcomeId = NULL, createStudyPopulationArgs)

Arguments

Details

Create a study population for a specific outcome, applying several restrictions.

Value

A list specifying the study population, with the following items:

• cases: A tibble with one row per observation period of a person with the outcome.

• outcomes: A tibble listing the days when a case has the outcome.

• metaData: A list with meta data about the study population, including the attrition.

Create a design matrix for a cyclic spline

Description

Create a design matrix for a cyclic spline

Usage

cyclicSplineDesign(x, knots, ord = 3)

Arguments

Details

This function is used by other functions in this package.

Export SCCSresults to CSV files

Description

Export SCCSresults to CSV files

Usage

exportToCsv(
  outputFolder,
  exportFolder = file.path(outputFolder, "export"),
  databaseId = 1,
  minCellCount = 5,
  maxCores = 1
)

Arguments

Details

This requires that runSccsAnalyses() has been executed first. It exports all the results in the outputFolder to CSV files for sharing with other sites.

Value

Does not return anything. Is called for the side-effect of populating the exportFolder with CSV files.

Fit the SCCS model

Description

Fit the SCCS model

Usage

fitSccsModel(sccsIntervalData, fitSccsModelArgs)

Arguments

Details

Fits the SCCS model as a conditional Poisson regression. When allowed, coefficients for some or all covariates can be regularized.

Likelihood profiling is only done for variables for which profileLikelihood is set to TRUE when calling createEraCovariateSettings(). Either specify the profileGrid for a completely user- defined grid, or profileBounds for an adaptive grid. Both should be defined on the log IRR scale. When both profileGrid and profileGrid are NULL likelihood profiling is disabled.

Value

An object of type SccsModel. Generic functions print, coef, and confint are available.

References

Suchard, M.A., Simpson, S.E., Zorych, I., Ryan, P., and Madigan, D. (2013). Massive parallelization of serial inference algorithms for complex generalized linear models. ACM Transactions on Modeling and Computer Simulation 23, 10

Get the attrition table for a population

Description

Get the attrition table for a population

Usage

getAttritionTable(object)

Arguments

Value

A tibble specifying the number of people and exposures in the population after specific steps of filtering.

Get database migrations instance

Description

Returns ResultModelManager DataMigrationsManager instance.

Usage

getDataMigrator(connectionDetails, databaseSchema, tablePrefix = "")

Arguments

Value

Instance of ResultModelManager::DataMigrationManager that has interface for converting existing data models

Load data for SCCS from the database

Description

Load all data needed to perform an SCCS analysis from the database.

Usage

getDbSccsData(
  connectionDetails,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  outcomeDatabaseSchema = cdmDatabaseSchema,
  outcomeTable = "condition_era",
  outcomeIds,
  exposureDatabaseSchema = cdmDatabaseSchema,
  exposureTable = "drug_era",
  customCovariateDatabaseSchema = cdmDatabaseSchema,
  customCovariateTable = "cohort",
  nestingCohortDatabaseSchema = cdmDatabaseSchema,
  nestingCohortTable = "cohort",
  getDbSccsDataArgs
)

Arguments

Details

This function downloads several types of information:

• Information on the occurrences of the outcome(s) of interest. Note that information for multiple outcomes can be fetched in one go, and later the specific outcome can be specified for which we want to build a model.

• Information on the observation time and age for the people with the outcomes.

• Information on exposures of interest which we want to include in the model.

Five different database schemas can be specified, for five different types of information: The

• cdmDatabaseSchema is used to extract patient age and observation period. The

• outcomeDatabaseSchema is used to extract information about the outcomes, the

• exposureDatabaseSchema is used to retrieve information on exposures, and the

• customCovariateDatabaseSchema is optionally used to find additional, user-defined covariates. All four locations could point to the same database schema.

• nestingCohortDatabaseSchema is optionally used to define a cohort in which the analysis is nested, for example a cohort of diabetics patients.

All five locations could point to the same database schema.

Cohort tables are assumed to have the following fields: cohort_definition_id, subject_id, cohort_start_date, and cohort_end_date.

Value

An SccsData object.

Study period start and end dates

A study start and end date define a period when patient data will be included in the analysis. Multiple non-overlapping periods can be defined, which for example will allow for excluding the time of the COVID pandemic, when most outcome rates were unstable.

Get a summary report of the analyses diagnostics

Description

Get a summary report of the analyses diagnostics

Usage

getDiagnosticsSummary(outputFolder)

Arguments

Value

A tibble containing summary diagnostics for each outcome-covariate-analysis combination.

Get file reference

Description

Get file reference

Usage

getFileReference(outputFolder)

Arguments

Value

A tibble containing the names of the files for various artifacts created for each outcome-exposures set.

Output the full model

Description

Output the full model

Usage

getModel(sccsModel)

Arguments

Value

A tibble with the coefficients and confidence intervals (when not-regularized) for all covariates in the model.

Get specifications for SelfControlledCaseSeries results data model

Description

Get specifications for SelfControlledCaseSeries results data model

Usage

getResultsDataModelSpecifications()

Value

A tibble data frame object with specifications

Get a summary report of the analyses results

Description

Get a summary report of the analyses results

Usage

getResultsSummary(outputFolder)

Arguments

Value

A tibble containing summary statistics for each outcome-covariate-analysis combination.

Does the model contain an age effect?

Description

Does the model contain an age effect?

Usage

hasAgeEffect(sccsModel)

Arguments

Value

TRUE if the model contains an age effect, otherwise FALSE.

Does the model contain an age effect?

Description

Does the model contain an age effect?

Usage

hasCalendarTimeEffect(sccsModel)

Arguments

Value

TRUE if the model contains an age effect, otherwise FALSE.

Does the model contain an age effect?

Description

Does the model contain an age effect?

Usage

hasSeasonality(sccsModel)

Arguments

Value

TRUE if the model contains an age effect, otherwise FALSE.

Check whether an object is a SccsData object

Description

Check whether an object is a SccsData object

Usage

isSccsData(x)

Arguments

Value

A logical value.

Check whether an object is a SccsIntervalData object

Description

Check whether an object is a SccsIntervalData object

Usage

isSccsIntervalData(x)

Arguments

Value

A logical value.

Load a list of ExposuresOutcome from file

Description

Load a list of objects of type ExposuresOutcome from file. The file is in JSON format.

Usage

loadExposuresOutcomeList(file)

Arguments

Value

A list of objects of type ExposuresOutcome.

Load a list of sccsAnalysis from file

Description

Load a list of objects of type SccsAnalysis from file. The file is in JSON format.

Usage

loadSccsAnalysisList(file)

Arguments

Value

A list of objects of type SccsAnalysis.

Load the cohort method data from a file

Description

Loads an object of type SccsData from a file in the file system.

Usage

loadSccsData(file)

Arguments

Value

An object of class SccsData.

Load the cohort method data from a file

Description

Loads an object of type SccsIntervalData from a file in the file system.

Usage

loadSccsIntervalData(file)

Arguments

Value

An object of class SccsIntervalData.

Migrate Data model

Description

Migrate data from current state to next state

It is strongly advised that you have a backup of all data (either sqlite files, a backup database (in the case you are using a postgres backend) or have kept the csv/zip files from your data generation.

Usage

migrateDataModel(connectionDetails, databaseSchema, tablePrefix = "")

Arguments

Plot the age effect

Description

Plot the age effect

Usage

plotAgeEffect(sccsModel, rrLim = c(0.1, 10), title = NULL, fileName = NULL)

Arguments

Details

Plot the spline curve of the age effect.

Value

A Ggplot object. Use the ggsave function to save to file.

Plot the age ranges spanned by each observation period.

Description

Plot the age ranges spanned by each observation period.

Usage

plotAgeSpans(
  studyPopulation,
  maxPersons = 10000,
  title = NULL,
  fileName = NULL
)

Arguments

Details

Plots a line per patient from their age at observation start to their age at observation end.

Value

A ggplot object. Use the ggplot2::ggsave() function to save to file in a different format.

Plot the calendar time effect

Description

Plot the calendar time effect

Usage

plotCalendarTimeEffect(
  sccsModel,
  rrLim = c(0.1, 10),
  title = NULL,
  fileName = NULL
)

Arguments

Details

Plot the spline curve of the calendar time effect.

Value

A Ggplot object. Use the ggsave function to save to file.

Plot the calendar time ranges spanned by each observation period.

Description

Plot the calendar time ranges spanned by each observation period.

Usage

plotCalendarTimeSpans(
  studyPopulation,
  maxPersons = 10000,
  title = NULL,
  fileName = NULL
)

Arguments

Details

Plots a line per patient from their observation start to their observation end.

Value

A ggplot object. Use the ggplot2::ggsave() function to save to file in a different format.

Plot time from event to observation end for censored and uncensored time.

Description

Plot time from event to observation end for censored and uncensored time.

Usage

plotEventObservationDependence(studyPopulation, title = NULL, fileName = NULL)

Arguments

Details

This plot shows whether there is a difference in time between (first) event and the observation period end for periods that are ' censored' and those that are 'uncensored'. By 'censored' we mean periods that end before we would normally expect. Here, we define periods to be uncensored if they end at either the study end date (if specified), database end date (i.e. the date after which no data is captured in the database), or maximum age (if specified). All other periods are assumed to be censored.

As proposed by Farrington et al., by comparing the two plots, we can gain some insight into whether the censoring is dependent on the occurrence of the event.

Value

A ggplot object. Use the ggplot2::ggsave() function to save to file in a different format.

References

Farrington P, Whitaker H, Ghebremichael Weldeselassie Y (2018), Self-controlled case series studies: A modelling guide with R, Taylor & Francis

Plot the ratio of observed to expected events over calendar time.

Description

Plot the ratio of observed to expected events over calendar time.

Usage

plotEventToCalendarTime(
  studyPopulation,
  sccsModel = NULL,
  title = NULL,
  fileName = NULL
)

Arguments

Details

Plot the ratio of observed to expected events over calendar time. The expected count expected rate considers which persons were observed during that month, and if specified in the model, the adjustment for season and calendar time.

Value

A ggplot object. Use the ggplot2::ggsave() function to save to file in a different format.

Plot information centered around the start of exposure

Description

Plot information centered around the start of exposure

Usage

plotExposureCentered(
  studyPopulation,
  sccsData,
  exposureEraId = NULL,
  highlightExposedEvents = TRUE,
  title = NULL,
  fileName = NULL
)

Arguments

Details

This plot shows the number of events and the number of subjects under observation in week-sized intervals relative to the start of the first exposure.

Value

A ggplot object. Use the ggplot2::ggsave() function to save to file in a different format.

Plot the seasonality effect

Description

Plot the seasonality effect

Usage

plotSeasonality(sccsModel, rrLim = c(0.1, 10), title = NULL, fileName = NULL)

Arguments

Details

Plot the spline curve of the seasonality effect.

Value

A Ggplot object. Use the ggsave function to save to file.

Run a list of analyses

Description

Run a list of analyses

Usage

runSccsAnalyses(
  connectionDetails,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  exposureDatabaseSchema = cdmDatabaseSchema,
  exposureTable = "drug_era",
  outcomeDatabaseSchema = cdmDatabaseSchema,
  outcomeTable = "cohort",
  customCovariateDatabaseSchema = cdmDatabaseSchema,
  customCovariateTable = "cohort",
  nestingCohortDatabaseSchema = cdmDatabaseSchema,
  nestingCohortTable = "cohort",
  outputFolder,
  sccsMultiThreadingSettings = createSccsMultiThreadingSettings(),
  sccsAnalysesSpecifications
)

Arguments

Details

Run a list of analyses for the exposures-outcomes of interest. This function will run all specified analyses against all hypotheses of interest, meaning that the total number of outcome models is length(sccsAnalysisList) * length(exposuresOutcomeList) When you provide several analyses it will determine whether any of the analyses have anything in common, and will take advantage of this fact.

Analyses to Exclude

Normally, runSccsAnalyses will run all combinations of exposures-outcome-analyses settings. However, sometimes we may not need all those combinations. Using the analysesToExclude argument, we can remove certain items from the full matrix. This argument should be a data frame with at least one of the following columns:

• exposureId

• outcomeId

• nestingCohortId

• analysisId

This data frame will be joined to the outcome model reference table before executing, and matching rows will be removed. For example, if one specifies only one exposure ID and analysis ID, then any analyses with that exposure and that analysis ID will be skipped.

Value

A tibble describing for each exposure-outcome-analysisId combination where the intermediary and outcome model files can be found, relative to the outputFolder.

Save a list of ExposuresOutcome to file

Description

Write a list of objects of type ExposuresOutcome to file. The file is in JSON format.

Usage

saveExposuresOutcomeList(exposuresOutcomeList, file)

Arguments

Save a list of SccsAnalysis to file

Description

Write a list of objects of type SccsAnalysis to file. The file is in JSON format.

Usage

saveSccsAnalysisList(sccsAnalysisList, file)

Arguments

Save the cohort method data to file

Description

Saves an object of type SccsData to a file.

Usage

saveSccsData(sccsData, file)

Arguments

Value

Returns no output.

Save the cohort method data to file

Description

Saves an object of type SccsIntervalData to a file.

Usage

saveSccsIntervalData(sccsIntervalData, file)

Arguments

Value

Returns no output.

Simulate SCCS data

Description

Simulate SCCS data

Usage

simulateSccsData(nCases, settings)

Arguments

Value

An object of type SccsData.

Upload results to the database server.

Description

Requires the results data model tables have been created using the createResultsDataModel function.

Usage

uploadResults(
  connectionDetails,
  schema,
  zipFileName,
  forceOverWriteOfSpecifications = FALSE,
  purgeSiteDataBeforeUploading = TRUE,
  tempFolder = tempdir(),
  tablePrefix = "",
  ...
)

Arguments