CohortMethod: Comparative Cohort Method with Large Scale Propensity and Outcome Models

Description

Functions for performing comparative cohort studies in an observational database in the Observational Medical Outcomes Partnership (OMOP) Common Data Model. Can extract all necessary data from a database. This implements large-scale propensity scores (LSPS) as described in Tian et al. (2018) doi:10.1093/ije/dyy120, using a large set of covariates, including for example all drugs, diagnoses, procedures, as well as age, comorbidity indexes, etc. Large scale regularized regression is used to fit the propensity and outcome models as described in Suchard et al. (2013) doi:10.1145/2414416.2414791. Functions are included for trimming, stratifying, (variable and fixed ratio) matching and weighting by propensity scores, as well as diagnostic functions, such as propensity score distribution plots and plots showing covariate balance before and after matching and/or trimming. Supported outcome models are (conditional) logistic regression, (conditional) Poisson regression, and (stratified) Cox regression. Also included are Kaplan-Meier plots that can adjust for the stratification or matching.

Author(s)

Maintainer: Martijn Schuemie schuemie@ohdsi.org

Authors:

• Marc Suchard

• Patrick Ryan

See Also

Useful links:

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

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

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

Cohort Method Data

Description

CohortMethodData is an S4 class that inherits from CoviarateData, which in turn inherits from Andromeda. It contains information on the cohorts, their outcomes, and baseline covariates. Information about multiple outcomes can be captured at once for efficiency reasons.

A CohortMethodData is typically created using getDbCohortMethodData(), can only be saved using saveCohortMethodData(), and loaded using loadCohortMethodData().

Usage

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

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

Arguments

Compute a weight-adjusted Kaplan-Meier curve

Description

Compute a weight-adjusted Kaplan-Meier curve

Usage

adjustedKm(weight, time, y)

Arguments

Check is CohortMethod and its dependencies are correctly installed

Description

Check is CohortMethod and its dependencies are correctly installed

Usage

checkCmInstallation(connectionDetails)

Arguments

Details

This function checks whether CohortMethod and its dependencies are correctly installed. This will check the database connectivity, large scale regression engine (Cyclops), and large data object handling (ff).

A simulation profile

Description

A simulation profile

Usage

data(cohortMethodDataSimulationProfile)

Compute covariate balance before and after PS adjustment

Description

For every covariate, prevalence in treatment and comparator groups before and after matching/trimming/weighting are computed. When variable ratio matching was used the balance score will be corrected according the method described in Austin et al (2008).

Usage

computeCovariateBalance(
  population,
  cohortMethodData,
  computeCovariateBalanceArgs = createComputeCovariateBalanceArgs()
)

Arguments

Details

The population data frame should have the following three columns:

• rowId (numeric): A unique identifier for each row (e.g. the person ID).

• treatment (integer): Column indicating whether the person is in the target (1) or comparator (0) group.

• propensityScore (numeric): Propensity score.

Value

Returns a tibble describing the covariate balance before and after PS adjustment, with one row per covariate, with the same data as the covariateRef table in the CohortMethodData object, and the following additional columns:

• beforeMatchingMeanTarget: The (weighted) mean value in the target before PS adjustment.

• beforeMatchingMeanComparator: The (weighted) mean value in the comparator before PS adjustment.

• beforeMatchingSumTarget: The (weighted) sum value in the target before PS adjustment.

• beforeMatchingSumComparator: The (weighted) sum value in the comparator before PS adjustment.

• beforeMatchingSdTarget: The standard deviation of the value in the target before PS adjustment.

• beforeMatchingSdComparator: The standard deviation of the value in the comparator before PS adjustment.

• beforeMatchingMean: The mean of the value across target and comparator before PS adjustment.

• beforeMatchingSd: The standard deviation of the value across target and comparator before PS adjustment.

• beforeMatchingStdDiff: The standardized difference of means when comparing the target to the comparator before PS adjustment.

• beforeMatchingSdmVariance: The variance of the standardized difference of the means when comparing the target to the comparator before PS adjustment.

• beforeMatchingSdmP : The P-value for whether abs(beforeMatchingStdDiff) exceeds the threshold.

• beforeMatchingBalanced : TRUE if the covariate is considered balanced between the target and comparator before PS adjustment (depending on the threshold and alpha settings).

• afterMatchingMeanTarget: The (weighted) mean value in the target after PS adjustment.

• afterMatchingMeanComparator: The (weighted) mean value in the comparator after PS adjustment.

• afterMatchingSumTarget: The (weighted) sum value in the target after PS adjustment.

• afterMatchingSumComparator: The (weighted) sum value in the comparator after PS adjustment.

• afterMatchingSdTarget: The standard deviation of the value in the target after PS adjustment.

• afterMatchingSdComparator: The standard deviation of the value in the comparator after PS adjustment.

• afterMatchingMean: The mean of the value across target and comparator after PS adjustment.

• afterMatchingSd: The standard deviation of the value across target and comparator after PS adjustment.

• afterMatchingStdDiff: The standardized difference of means when comparing the target to the comparator after PS adjustment.

• afterMatchingSdmVariance: The variance of the standardized difference of the means when comparing the target to the comparator after PS adjustment.

• afteMatchingSdmP : The P-value for whether abs(beforeMatchingStdDiff) exceeds the threshold.

• afteMatchingBalanced : TRUE if the covariate is considered balanced between the target and comparator before PS adjustment (depending on the threshold and alpha settings).

• targetStdDiff: The standardized difference of means when comparing the target before PS adjustment to the target after PS adjustment.

• comparatorStdDiff: The standardized difference of means when comparing the comparator before PS adjustment to the comparator after PS adjustment. -targetComparatorStdDiff: The standardized difference of means when comparing the entire population before PS adjustment to the entire population after PS adjustment.

The 'beforeMatchingStdDiff' and 'afterMatchingStdDiff' columns inform on the balance: are the target and comparator sufficiently similar in terms of baseline covariates to allow for valid causal estimation?

The 'targetStdDiff', 'comparatorStdDiff', and 'targetComparatorStdDiff' columns inform on the generalizability: are the cohorts after PS adjustment sufficiently similar to the cohorts before adjustment to allow generalizing the findings to the original cohorts?

References

Austin, PC (2008) Assessing balance in measured baseline covariates when using many-to-one matching on the propensity-score. Pharmacoepidemiology and Drug Safety, 17: 1218-1225.

Hripcsak G, Zhang L, Chen Y, Li K, Suchard MA, Ryan PB, Schuemie MJ (2025) Assessing Covariate Balance with Small Sample Sizes. Stat Med. 2025 Aug;44(18-19):e70212.

Compute fraction in equipoise

Description

Compute fraction in equipoise

Usage

computeEquipoise(data, equipoiseBounds = c(0.3, 0.7))

Arguments

Details

Computes the fraction of the population (the union of the target and comparator cohorts) who are in clinical equipoise (i.e. who had a reasonable chance of receiving either target or comparator, based on the baseline characteristics).

The data frame should have a least the following two columns:

• treatment (integer): Column indicating whether the person is in the target (1) or comparator (0) group

• propensityScore (numeric): Propensity score

Value

A numeric value (fraction in equipoise) between 0 and 1.

References

Walker AM, Patrick AR, Lauer MS, Hornbrook MC, Marin MG, Platt R, Roger VL, Stang P, and Schneeweiss S. (2013) A tool for assessing the feasibility of comparative effectiveness research, Comparative Effective Research, 3, 11-20

Compute the minimum detectable relative risk

Description

Compute the minimum detectable relative risk

Usage

computeMdrr(
  population,
  alpha = 0.05,
  power = 0.8,
  twoSided = TRUE,
  modelType = "cox"
)

Arguments

Details

Compute the minimum detectable relative risk (MDRR) and expected standard error (SE) for a given study population, using the actual observed sample size and number of outcomes. Currently, only computations for Cox and logistic models are implemented. For Cox model, the computations by Schoenfeld (1983) is used. For logistic models Wald's z-test is used.

Value

A data frame with the MDRR and some counts.

References

Schoenfeld DA (1983) Sample-size formula for the proportional-hazards regression model, Biometrics, 39(3), 499-503

Compute the area under the ROC curve

Description

Compute the area under the ROC curve of the propensity score.

Usage

computePsAuc(data, confidenceIntervals = FALSE, maxRows = 1e+05)

Arguments

Details

The data frame should have a least the following two columns:

• treatment (integer): Column indicating whether the person is in the target (1) or comparator (0) group.

• propensityScore (numeric): Propensity score.

Value

A tibble holding the AUC and its 95 percent confidence interval

Examples

treatment <- rep(0:1, each = 100)
propensityScore <- c(rnorm(100, mean = 0.4, sd = 0.25), rnorm(100, mean = 0.6, sd = 0.25))
data <- data.frame(treatment = treatment, propensityScore = propensityScore)
data <- data[data$propensityScore > 0 & data$propensityScore < 1, ]
computePsAuc(data)

Convert untyped list to SccsAnalysesSpecifications

Description

Convert untyped list to SccsAnalysesSpecifications

Usage

convertUntypedListToCmAnalysesSpecifications(untypedList)

Arguments

Value

An object of type SccsAnalysesSpecifications.

Create full CM analysis specifications

Description

Create full CM analysis specifications

Usage

createCmAnalysesSpecifications(
  cmAnalysisList,
  targetComparatorOutcomesList,
  analysesToExclude = NULL,
  refitPsForEveryOutcome = FALSE,
  refitPsForEveryStudyPopulation = TRUE,
  cmDiagnosticThresholds = createCmDiagnosticThresholds()
)

Arguments

Details

Analyses to Exclude

Normally, runCmAnalyses will run all combinations of target-comparator-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:

• targetId

• comparatorId

• nestingCohortId

• outcomeId

• 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 target ID and analysis ID, then any analyses with that target and that analysis ID will be skipped.

Value

An object of type CmAnalysesSpecifications.

Create a CohortMethod analysis specification

Description

Create a CohortMethod analysis specification

Usage

createCmAnalysis(
  analysisId = 1,
  description = "",
  getDbCohortMethodDataArgs,
  createStudyPopulationArgs,
  createPsArgs = NULL,
  trimByPsArgs = NULL,
  truncateIptwArgs = NULL,
  matchOnPsArgs = NULL,
  stratifyByPsArgs = NULL,
  computeSharedCovariateBalanceArgs = NULL,
  computeCovariateBalanceArgs = NULL,
  fitOutcomeModelArgs = NULL
)

Arguments

Details

Create a set of analysis choices, to be used with the runCmAnalyses() function.

Providing a NULL value for any of the argument applies the corresponding step will not be executed. For example, if createPsArgs = NULL, no propensity scores will be computed.

Value

An object of type CmAnalysis, to be used with the runCmAnalyses function.

Create CohortMethod diagnostics thresholds

Description

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

Usage

createCmDiagnosticThresholds(
  mdrrThreshold = 10,
  easeThreshold = 0.25,
  sdmThreshold = 0.1,
  sdmAlpha = NULL,
  equipoiseThreshold = 0.2,
  generalizabilitySdmThreshold = 999
)

Arguments

Details

The sdmThreshold and sdmAlpha arguments are independent of the threshold and alpha threshold provided to the createComputeCovariateBalanceArgs() function. The latter have no impact on blinding and diagnostics reported in the export.

Value

An object of type CmDiagnosticThresholds.

Create a table 1

Description

Creates a formatted table of cohort characteristics, to be included in publications or reports.

Usage

createCmTable1(
  balance,
  specifications = getDefaultCmTable1Specifications(),
  beforeTargetPopSize = NULL,
  beforeComparatorPopSize = NULL,
  afterTargetPopSize = NULL,
  afterComparatorPopSize = NULL,
  beforeLabel = "Before matching",
  afterLabel = "After matching",
  targetLabel = "Target",
  comparatorLabel = "Comparator",
  percentDigits = 1,
  stdDiffDigits = 2
)

Arguments

Value

A data frame with the formatted table 1.

Create simulation profile

Description

Creates a profile based on the provided CohortMethodData object, which can be used to generate simulated data that has similar characteristics.

Usage

createCohortMethodDataSimulationProfile(cohortMethodData, minCellCount = 5)

Arguments

Details

The output of this function is an object that can be used by the simulateCohortMethodData() function to generate a cohortMethodData object.

Value

An object of type CohortDataSimulationProfile.

Create a parameter object for the function computeCovariateBalance()

Description

Create a parameter object for the function computeCovariateBalance()

Usage

createComputeCovariateBalanceArgs(
  subgroupCovariateId = NULL,
  maxCohortSize = 250000,
  covariateFilter = NULL,
  threshold = 0.1,
  alpha = 0.05
)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type ComputeCovariateBalanceArgs.

References

Hripcsak G, Zhang L, Chen Y, Li K, Suchard MA, Ryan PB, Schuemie MJ, Assessing Covariate Balance with Small Sample Sizes. Statistics in Medicine 44, no. 18-19 (2025): e70212

Create a parameter object for the function createPs()

Description

Create a parameter object for the function createPs()

Usage

createCreatePsArgs(
  excludeCovariateIds = c(),
  includeCovariateIds = c(),
  maxCohortSizeForFitting = 250000,
  errorOnHighCorrelation = TRUE,
  stopOnError = TRUE,
  prior = createPrior(priorType = "laplace", exclude = c(0), useCrossValidation = TRUE),
  control = createControl(noiseLevel = "silent", cvType = "auto", seed = 1,
    resetCoefficients = TRUE, tolerance = 2e-07, cvRepetitions = 10, startingVariance =
    0.01),
  estimator = "att"
)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type CreatePsArgs.

Create a parameter object for the function createStudyPopulation()

Description

Create a parameter object for the function createStudyPopulation()

Usage

createCreateStudyPopulationArgs(
  removeSubjectsWithPriorOutcome = TRUE,
  priorOutcomeLookback = 99999,
  minDaysAtRisk = 1,
  maxDaysAtRisk = 99999,
  riskWindowStart = 0,
  startAnchor = "cohort start",
  riskWindowEnd = 0,
  endAnchor = "cohort end",
  censorAtNewRiskWindow = FALSE
)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type CreateStudyPopulationArgs.

Create default CohortMethod multi-threading settings

Description

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

Usage

createDefaultMultiThreadingSettings(maxCores)

Arguments

Value

An object of type CmMultiThreadingSettings.

See Also

createMultiThreadingSettings()

Examples

settings <- createDefaultMultiThreadingSettings(10)

Create a parameter object for the function fitOutcomeModel()

Description

Create a parameter object for the function fitOutcomeModel()

Usage

createFitOutcomeModelArgs(
  modelType = "cox",
  stratified = FALSE,
  useCovariates = FALSE,
  inversePtWeighting = FALSE,
  bootstrapCi = FALSE,
  bootstrapReplicates = 200,
  interactionCovariateIds = c(),
  excludeCovariateIds = c(),
  includeCovariateIds = c(),
  profileGrid = NULL,
  profileBounds = c(log(0.1), log(10)),
  prior = createPrior(priorType = "laplace", useCrossValidation = TRUE),
  control = createControl(cvType = "auto", seed = 1, resetCoefficients = TRUE,
    startingVariance = 0.01, tolerance = 2e-07, cvRepetitions = 10, noiseLevel = "quiet")
)

Arguments

Details

Create an object defining the parameter values.

For likelihood profiling, either specify the profileGrid for a completely user- defined grid, or profileBounds for an adaptive grid. Both should be defined on the log effect size scale. When both profileGrid and profileGrid are NULL likelihood profiling is disabled.

Value

An object of type ComputeCovariateBalanceArgs.

Create a parameter object for the function getDbCohortMethodData()

Description

Create a parameter object for the function getDbCohortMethodData()

Usage

createGetDbCohortMethodDataArgs(
  removeDuplicateSubjects = "keep first, truncate to second",
  firstExposureOnly = TRUE,
  washoutPeriod = 365,
  nestingCohortId = NULL,
  restrictToCommonPeriod = TRUE,
  minAge = NULL,
  maxAge = NULL,
  genderConceptIds = NULL,
  studyStartDate = "",
  studyEndDate = "",
  maxCohortSize = 0,
  covariateSettings
)

Arguments

Details

Create an object defining the parameter values.

The removeduplicateSubjects argument can have one of the following values:

• "keep first, truncate to second": When a subjects appear in both target and comparator cohort, only keep whichever cohort is first in time. If the other cohort starts before the first has ended, the first cohort will be truncated to stop the day before the second starts. If both cohorts start simultaneous, the person is removed from the analysis.

• "keep first": When a subjects appear in both target and comparator cohort, only keep whichever cohort is first in time. If both cohorts start simultaneous, the person is removed from the analysis.

• "remove all": Remove subjects that appear in both target and comparator cohort completely from the analysis."

• "keep all": Do not remove subjects that appear in both target and comparator cohort

Value

An object of type GetDbCohortMethodDataArgs.

Create a parameter object for the function matchOnPs()

Description

Create a parameter object for the function matchOnPs()

Usage

createMatchOnPsArgs(
  caliper = 0.2,
  caliperScale = "standardized logit",
  maxRatio = 1,
  allowReverseMatch = FALSE,
  matchColumns = c(),
  matchCovariateIds = c()
)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type MatchOnPsArgs.

References

Austin, PC. (2011) Optimal caliper widths for propensity-score matching when estimating differences in means and differences in proportions in observational studies, Pharmaceutical statistics, March, 10(2):150-161.

Create CohortMethod multi-threading settings

Description

Create CohortMethod multi-threading settings

Usage

createMultiThreadingSettings(
  getDbCohortMethodDataThreads = 1,
  createPsThreads = 1,
  psCvThreads = 1,
  createStudyPopThreads = 1,
  trimMatchStratifyThreads = 1,
  computeSharedBalanceThreads = 1,
  computeBalanceThreads = 1,
  prefilterCovariatesThreads = 1,
  fitOutcomeModelThreads = 1,
  outcomeCvThreads = 1,
  calibrationThreads = 1
)

Arguments

Value

An object of type CmMultiThreadingSettings.

See Also

createDefaultMultiThreadingSettings()

Create outcome definition

Description

Create outcome definition

Usage

createOutcome(
  outcomeId,
  outcomeOfInterest = TRUE,
  trueEffectSize = NA,
  priorOutcomeLookback = NULL,
  riskWindowStart = NULL,
  startAnchor = NULL,
  riskWindowEnd = NULL,
  endAnchor = NULL
)

Arguments

Details

Any settings here that are not NULL will override any values set in createCreateStudyPopulationArgs().

Value

An object of type Outcome, to be used in createTargetComparatorOutcomes().

Create propensity scores

Description

Creates propensity scores and inverse probability of treatment weights (IPTW) using a regularized logistic regression.

Usage

createPs(
  cohortMethodData,
  population = NULL,
  createPsArgs = createCreatePsArgs()
)

Arguments

Details

IPTW estimates either the average treatment effect (ate) or average treatment effect in the treated (att) using stabilized inverse propensity scores (Xu et al. 2010).

References

Xu S, Ross C, Raebel MA, Shetterly S, Blanchette C, Smith D. Use of stabilized inverse propensity scores as weights to directly estimate relative risk and its confidence intervals. Value Health. 2010;13(2):273-277. doi:10.1111/j.1524-4733.2009.00671.x

Examples

data(cohortMethodDataSimulationProfile)
cohortMethodData <- simulateCohortMethodData(cohortMethodDataSimulationProfile, n = 1000)
ps <- createPs(cohortMethodData, createPsArgs = createCreatePsArgs())

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 a parameter object for the function stratifyByPs()

Description

Create a parameter object for the function stratifyByPs()

Usage

createStratifyByPsArgs(
  numberOfStrata = 10,
  baseSelection = "all",
  stratificationColumns = c(),
  stratificationCovariateIds = c()
)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type StratifyByPsArgs.

Create a study population

Description

Create a study population

Usage

createStudyPopulation(
  cohortMethodData,
  population = NULL,
  outcomeId = NULL,
  createStudyPopulationArgs = createCreateStudyPopulationArgs()
)

Arguments

Details

Create a study population by enforcing certain inclusion and exclusion criteria, defining a risk window, and determining which outcomes fall inside the risk window.

Value

A tibble specifying the study population. This tibble will have the following columns:

• rowId: A unique identifier for an exposure.

• personSeqId: The person sequence ID of the subject.

• cohortStartdate: The index date.

• outcomeCount The number of outcomes observed during the risk window.

• timeAtRisk: The number of days in the risk window.

• survivalTime: The number of days until either the outcome or the end of the risk window.

Create target-comparator-outcomes combinations.

Description

Create target-comparator-outcomes combinations.

Usage

createTargetComparatorOutcomes(
  targetId,
  comparatorId,
  outcomes,
  nestingCohortId = NULL,
  excludedCovariateConceptIds = c(),
  includedCovariateConceptIds = c()
)

Arguments

Details

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

Value

An object of type TargetComparatorOutcomes.

Create a parameter object for the function trimByPs()

Description

Create a parameter object for the function trimByPs()

Usage

createTrimByPsArgs(
  trimFraction = NULL,
  equipoiseBounds = NULL,
  maxWeight = NULL,
  trimMethod = "symmetric"
)

Arguments

Details

Create an object defining the parameter values. Set any argument to NULL to not use it for trimming.

Value

An object of type TrimByPsArgs.

References

Walker AM, Patrick AR, Lauer MS, Hornbrook MC, Marin MG, Platt R, Roger VL, Stang P, and Schneeweiss S. (2013) A tool for assessing the feasibility of comparative effectiveness research, Comparative Effective Research, 3, 11-20

Crump, Richard K., V. Joseph Hotz, Guido W. Imbens, and Oscar A. Mitnik. 2009. Dealing with limited overlap in estimation of average treatment effects. Biometrika 96(1): 187-199.

Sturmer T, Rothman KJ, Avorn J, Glynn RJ. Treatment effects in the presence of unmeasured confounding: dealing with observations in the tails of the propensity score distribution–a simulation study. Am J Epidemiol. 2010 Oct 1;172(7):843-54.

Create a parameter object for the function truncateIptw()

Description

Create a parameter object for the function truncateIptw()

Usage

createTruncateIptwArgs(maxWeight = 10)

Arguments

Details

Create an object defining the parameter values.

Value

An object of type TruncateIptwArgs.

Draw the attrition diagram

Description

drawAttritionDiagram draws the attrition diagram, showing how many people were excluded from the study population, and for what reasons.

Usage

drawAttritionDiagram(
  object,
  targetLabel = "Target",
  comparatorLabel = "Comparator",
  fileName = NULL
)

Arguments

Value

A ggplot object. Use the ggsave function to save to file in a different format.

Export cohort method results to CSV files

Description

Export cohort method results to CSV files

Usage

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

Arguments

Details

This requires that runCmAnalyses() 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.

Create an outcome model, and compute the relative risk

Description

Create an outcome model, and computes the relative risk

Usage

fitOutcomeModel(
  population,
  cohortMethodData = NULL,
  fitOutcomeModelArgs = createFitOutcomeModelArgs()
)

Arguments

Details

For likelihood profiling, either specify the profileGrid for a completely user- defined grid, or profileBounds for an adaptive grid. Both should be defined on the log effect size scale. When both profileGrid and profileGrid are NULL likelihood profiling is disabled.

Value

An object of class OutcomeModel. Generic function print, coef, and confint are available.

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

Get the cohort data from the server

Description

This function executes a large set of SQL statements against the database in OMOP CDM format to extract the data needed to perform the analysis.

Usage

getDbCohortMethodData(
  connectionDetails,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  targetId,
  comparatorId,
  outcomeIds,
  exposureDatabaseSchema = cdmDatabaseSchema,
  exposureTable = "drug_era",
  outcomeDatabaseSchema = cdmDatabaseSchema,
  outcomeTable = "condition_occurrence",
  nestingCohortDatabaseSchema = cdmDatabaseSchema,
  nestingCohortTable = "cohort",
  getDbCohortMethodDataArgs = createGetDbCohortMethodDataArgs()
)

Arguments

Details

Based on the arguments, the treatment and comparator cohorts are retrieved, as well as outcomes occurring in exposed subjects. The treatment and comparator cohorts can be identified using the DRUG_ERA table, or through user-defined cohorts in a cohort table either inside the CDM schema or in a separate schema. Similarly, outcomes are identified using the CONDITION_ERA table or through user-defined cohorts in a cohort table either inside the CDM schema or in a separate schema. Optionally, the target and comparator cohorts can be restricted to be within a nesting cohort, which can reside in a different database schema and table.

Value

A CohortMethodData object.

Get the default table 1 specifications

Description

Loads the default specifications for a table 1, to be used with the createCmTable1 function.

Important: currently only works for binary covariates.

Usage

getDefaultCmTable1Specifications()

Value

A specifications objects.

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 file names of artifacts generated for each target-comparator-outcome-analysis combination.

Get the distribution of follow-up time

Description

Get the distribution of follow-up time

Usage

getFollowUpDistribution(population, quantiles = c(0, 0.25, 0.5, 0.75, 1))

Arguments

Details

Get the distribution of follow-up time as quantiles. Follow-up time is defined as time-at-risk, so not censored at the outcome.

Value

A data frame with per treatment group at each quantile the amount of follow-up time available.

Get information on generalizability

Description

to assess generalizability we compare the distribution of covariates before and after any (propensity score) adjustments. We compute the standardized difference of mean as our metric of generalizability. (Lipton et al., 2017)

Depending on our target estimand, we need to consider a different base population for generalizability. For example, if we aim to estimate the average treatment effect in the treated (ATT), our base population should be the target population, meaning we should consider the covariate distribution before and after PS adjustment in the target population only. By default this function will attempt to select the right base population based on what operations have been performed on the population. For example, if PS matching has been performed we assume the target estimand is the ATT, and the target population is selected as base.

Requires running computeCovariateBalance()' first.

Usage

getGeneralizabilityTable(balance, baseSelection = "auto")

Arguments

Value

A tibble with the following columns:

• covariateId: The ID of the covariate. Can be linked to the covariates and covariateRef tables in the CohortMethodData object.

• covariateName: The name of the covariate.

• beforeMatchingMean: The mean covariate value before any (propensity score) adjustment.

• afterMatchingMean: The mean covariate value after any (propensity score) adjustment.

• stdDiff: The standardized difference of means between before and after adjustment.

The tibble also has a 'baseSelection' attribute, documenting the base population used to assess generalizability.

References

Tipton E, Hallberg K, Hedges LV, Chan W (2017) Implications of Small Samples for Generalization: Adjustments and Rules of Thumb, Eval Rev. Oct;41(5):472-505.

Get a summary report of the analyses results

Description

Get a summary report of the analyses results

Usage

getInteractionResultsSummary(outputFolder)

Arguments

Value

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

Get the outcome model

Description

Get the full outcome model, so showing the betas of all variables included in the outcome model, not just the treatment variable.

Usage

getOutcomeModel(outcomeModel, cohortMethodData)

Arguments

Value

A tibble.

Get the propensity model

Description

Returns the coefficients and names of the covariates with non-zero coefficients.

Usage

getPsModel(propensityScore, cohortMethodData)

Arguments

Value

A tibble.

Get specifications for CohortMethod results data model

Description

Get specifications for CohortMethod 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 target-comparator-outcome-analysis combination.

Check whether an object is a CohortMethodData object

Description

Check whether an object is a CohortMethodData object

Usage

isCohortMethodData(x)

Arguments

Value

A logical value.

Load a list of CmAnalysis from file

Description

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

Usage

loadCmAnalysisList(file)

Arguments

Value

A list of objects of type CmAnalysis.

Load the cohort method data from a file

Description

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

Usage

loadCohortMethodData(file)

Arguments

Value

An object of class CohortMethodData.

Load a list of TargetComparatorOutcomes from file

Description

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

Usage

loadTargetComparatorOutcomesList(file)

Arguments

Value

A list of objects of type TargetComparatorOutcomes.

Match persons by propensity score

Description

Use the provided propensity scores to match target to comparator persons.

Usage

matchOnPs(
  population,
  matchOnPsArgs = createMatchOnPsArgs(),
  cohortMethodData = NULL
)

Arguments

Details

The data frame should have the following three columns:

• rowId (numeric): A unique identifier for each row (e.g. the person ID).

• treatment (integer): Column indicating whether the person is in the target (1) or comparator (0) group.

• propensityScore (numeric): Propensity score.

The default caliper (0.2 on the standardized logit scale) is the one recommended by Austin (2011).

Value

Returns a date frame with the same columns as the input data plus one extra column: stratumId. Any rows that could not be matched are removed

References

Rassen JA, Shelat AA, Myers J, Glynn RJ, Rothman KJ, Schneeweiss S. (2012) One-to-many propensity score matching in cohort studies, Pharmacoepidemiology and Drug Safety, May, 21 Suppl 2:69-80.

Austin, PC. (2011) Optimal caliper widths for propensity-score matching when estimating differences in means and differences in proportions in observational studies, Pharmaceutical statistics, March, 10(2):150-161.

Examples

rowId <- 1:5
treatment <- c(1, 0, 1, 0, 1)
propensityScore <- c(0, 0.1, 0.3, 0.4, 1)
age_group <- c(1, 1, 1, 1, 1)
data <- data.frame(
  rowId = rowId,
  treatment = treatment,
  propensityScore = propensityScore,
  age_group = age_group
)
result <- matchOnPs(data, createMatchOnPsArgs(
  caliper = 0,
  maxRatio = 1,
  matchColumns = "age_group")
)

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 variables with largest imbalance

Description

Create a plot showing those variables having the largest imbalance before matching, and those variables having the largest imbalance after matching. Requires running computeCovariateBalance first.

Usage

plotCovariateBalanceOfTopVariables(
  balance,
  n = 20,
  maxNameWidth = 100,
  title = NULL,
  fileName = NULL,
  beforeLabel = "before matching",
  afterLabel = "after matching"
)

Arguments

Value

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

Create a scatterplot of the covariate balance

Description

Create a scatterplot of the covariate balance, showing all variables with balance before and after matching on the x and y axis respectively. Requires running computeCovariateBalance first.

Usage

plotCovariateBalanceScatterPlot(
  balance,
  absolute = TRUE,
  threshold = 0,
  title = "Standardized difference of mean",
  fileName = NULL,
  beforeLabel = "Before matching",
  afterLabel = "After matching",
  showCovariateCountLabel = FALSE,
  showMaxLabel = FALSE,
  showUnbalanced = FALSE
)

Arguments

Value

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

Plot covariate prevalence

Description

Plot prevalence of binary covariates in the target and comparator cohorts, before and after matching. Requires running computeCovariateBalance first.

Usage

plotCovariatePrevalence(
  balance,
  threshold = 0,
  title = "Covariate prevalence",
  fileName = NULL,
  beforeLabel = "Before matching",
  afterLabel = "After matching",
  targetLabel = "Target",
  comparatorLabel = "Comparator"
)

Arguments

Value

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

Plot the distribution of follow-up time

Description

Plot the distribution of follow-up time

Usage

plotFollowUpDistribution(
  population,
  targetLabel = "Target",
  comparatorLabel = "Comparator",
  yScale = "percent",
  logYScale = FALSE,
  dataCutoff = 0.95,
  title = NULL,
  fileName = NULL
)

Arguments

Details

Plot the distribution of follow-up time, stratified by treatment group.Follow-up time is defined as time-at-risk, so not censored at the outcome.

Value

A ggplot object. Use the ggsave function to save to file in a different format.

Plot the Kaplan-Meier curve

Description

plotKaplanMeier creates the Kaplan-Meier (KM) survival plot. Based (partially) on recommendations in Pocock et al (2002).

When variable-sized strata are detected, an adjusted KM plot is computed to account for stratified data, as described in Galimberti eta al (2002), using the closed form variance estimator described in Xie et al (2005).

Usage

plotKaplanMeier(
  population,
  censorMarks = FALSE,
  confidenceIntervals = TRUE,
  includeZero = FALSE,
  dataTable = TRUE,
  dataCutoff = 0.9,
  targetLabel = "Treated",
  comparatorLabel = "Comparator",
  title = NULL,
  fileName = NULL
)

Arguments

Value

A ggplot object. Use the ggsave function to save to file in a different format.

References

Pocock SJ, Clayton TC, Altman DG. (2002) Survival plots of time-to-event outcomes in clinical trials: good practice and pitfalls, Lancet, 359:1686-89.

Galimberti S, Sasieni P, Valsecchi MG (2002) A weighted Kaplan-Meier estimator for matched data with application to the comparison of chemotherapy and bone-marrow transplant in leukaemia. Statistics in Medicine, 21(24):3847-64.

Xie J, Liu C. (2005) Adjusted Kaplan-Meier estimator and log-rank test with inverse probability of treatment weighting for survival data. Statistics in Medicine, 26(10):2276.

Plot the propensity score distribution

Description

Plots the propensity (or preference) score distribution.

Usage

plotPs(
  data,
  unfilteredData = NULL,
  scale = "preference",
  type = "density",
  binWidth = 0.05,
  targetLabel = "Target",
  comparatorLabel = "Comparator",
  showCountsLabel = FALSE,
  showAucLabel = FALSE,
  showEquipoiseLabel = FALSE,
  equipoiseBounds = c(0.3, 0.7),
  unitOfAnalysis = "subjects",
  title = NULL,
  fileName = NULL
)

Arguments

Details

The data frame should have a least the following two columns:

• treatment (integer): Column indicating whether the person is in the target (1) or comparator (0) group

• propensityScore (numeric): Propensity score

Value

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

References

Walker AM, Patrick AR, Lauer MS, Hornbrook MC, Marin MG, Platt R, Roger VL, Stang P, and Schneeweiss S. (2013) A tool for assessing the feasibility of comparative effectiveness research, Comparative Effective Research, 3, 11-20

Examples

treatment <- rep(0:1, each = 100)
propensityScore <- c(rnorm(100, mean = 0.4, sd = 0.25), rnorm(100, mean = 0.6, sd = 0.25))
data <- data.frame(treatment = treatment, propensityScore = propensityScore)
data <- data[data$propensityScore > 0 & data$propensityScore < 1, ]
plotPs(data)

Plot time-to-event

Description

Plot time-to-event

Usage

plotTimeToEvent(
  cohortMethodData,
  population = NULL,
  outcomeId = NULL,
  minDaysAtRisk = 1,
  riskWindowStart = 0,
  startAnchor = "cohort start",
  riskWindowEnd = 0,
  endAnchor = "cohort end",
  censorAtNewRiskWindow = FALSE,
  periodLength = 7,
  numberOfPeriods = 52,
  highlightExposedEvents = TRUE,
  includePostIndexTime = TRUE,
  showFittedLines = TRUE,
  targetLabel = "Target",
  comparatorLabel = "Comparator",
  title = NULL,
  fileName = NULL
)

Arguments

Details

Creates a plot showing the number of events over time in the target and comparator cohorts, both before and after index date. The plot also distinguishes between events inside and outside the time-at-risk period. This requires the user to (re)specify the time-at-risk using the same arguments as the createStudyPopulation() function. Note that it is not possible to specify that people with the outcome prior should be removed, since the plot will show these prior events.

Value

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

Run a list of analyses

Description

Run a list of analyses

Usage

runCmAnalyses(
  connectionDetails,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  exposureDatabaseSchema = cdmDatabaseSchema,
  exposureTable = "drug_era",
  outcomeDatabaseSchema = cdmDatabaseSchema,
  outcomeTable = "condition_occurrence",
  nestingCohortDatabaseSchema = cdmDatabaseSchema,
  nestingCohortTable = "cohort",
  outputFolder = "./CohortMethodOutput",
  multiThreadingSettings = createMultiThreadingSettings(),
  cmAnalysesSpecifications
)

Arguments

Details

Run a list of analyses for the target-comparator-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(cmAnalysisList) * length(targetComparatorOutcomesList) (if all analyses specify an outcome model should be fitted). When you provide several analyses it will determine whether any of the analyses have anything in common, and will take advantage of this fact. For example, if we specify several analyses that only differ in the way the outcome model is fitted, then this function will extract the data and fit the propensity model only once, and re-use this in all the analysis.

After completion, a tibble containing references to all generated files can be obtained using the getFileReference() function. A summary of the analysis results can be obtained using the getResultsSummary() function. Diagnostics can be loaded using the getDiagnosticsSummary() function.

Value

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

Save a list of CmAnalysis to file

Description

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

Usage

saveCmAnalysisList(CmAnalysisList, file)

Arguments

Save the cohort method data to file

Description

Saves an object of type CohortMethodData to a file.

Usage

saveCohortMethodData(cohortMethodData, file)

Arguments

Value

Returns no output.

Save a list of TargetComparatorOutcomes to file

Description

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

Usage

saveTargetComparatorOutcomesList(targetComparatorOutcomesList, file)

Arguments

Generate simulated data

Description

Creates a CohortMethodData object with simulated data.

Usage

simulateCohortMethodData(profile, n = 10000)

Arguments

Details

This function generates simulated data that is in many ways similar to the original data on which the simulation profile is based. The contains same outcome, comparator, and outcome concept IDs, and the covariates and their 1st order statistics should be comparable.

Value

An object of type CohortMethodData.

Stratify persons by propensity score

Description

Use the provided propensity scores to stratify persons. Additional stratification variables for stratifications can also be used.

Usage

stratifyByPs(
  population,
  stratifyByPsArgs = createStratifyByPsArgs(),
  cohortMethodData = NULL
)

Arguments

Details

The data frame should have the following three columns:

• rowId (numeric): A unique identifier for each row (e.g. the person ID).

• treatment (integer): Column indicating whether the person is in the target (1) or comparator (0) group.

• propensityScore (numeric): Propensity score.

Value

Returns a tibble with the same columns as the input data plus one extra column: stratumId.

Examples

rowId <- 1:200
treatment <- rep(0:1, each = 100)
propensityScore <- c(runif(100, min = 0, max = 1), runif(100, min = 0, max = 1))
data <- data.frame(rowId = rowId, treatment = treatment, propensityScore = propensityScore)
result <- stratifyByPs(data, createStratifyByPsArgs(numberOfStrata = 5))

Trim persons by propensity score

Description

Use the provided propensity scores to trim subjects with extreme scores or weights.

Usage

trimByPs(population, trimByPsArgs = createTrimByPsArgs(trimFraction = 0.05))

Arguments

Details

The data frame should have the following three columns:

• rowId (numeric): A unique identifier for each row (e.g. the person ID).

• treatment (integer): Column indicating whether the person is in the target (1) or comparator (0) group.

• propensityScore (numeric): Propensity score.

Value

Returns a tibble with the same three columns as the input.

Examples

rowId <- 1:2000
treatment <- rep(0:1, each = 1000)
propensityScore <- c(runif(1000, min = 0, max = 1), runif(1000, min = 0, max = 1))
iptw <- ifelse(treatment == 1,
               mean(treatment == 1) / propensityScore,
               mean(treatment == 0) / (1 - propensityScore))
data <- data.frame(rowId = rowId,
                   treatment = treatment,
                   propensityScore = propensityScore,
                   iptw = iptw)
result1 <- trimByPs(data, createTrimByPsArgs(trimFraction = 0.05))
result2 <- trimByPs(data, createTrimByPsArgs(equipoiseBounds = c(0.3, 0.7)))
result3 <- trimByPs(data, createTrimByPsArgs(maxWeight = 10))

Truncate IPTW values

Description

Set the inverse probability of treatment weights (IPTW) to the user-specified threshold if it exceeds said threshold.

Usage

truncateIptw(population, truncateIptwArgs = createTruncateIptwArgs())

Arguments

Details

The data frame should have the following two columns:

• treatment (integer): Column indicating whether the person is in the target (1) or comparator (0) group.

• iptw (numeric): Propensity score.

Value

Returns a tibble with the same columns as the input.

Examples

rowId <- 1:2000
treatment <- rep(0:1, each = 1000)
iptw <- 1 / c(runif(1000, min = 0, max = 1), runif(1000, min = 0, max = 1))
data <- data.frame(rowId = rowId, treatment = treatment, iptw = iptw)
result <- truncateIptw(data)

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