EvidenceSynthesis: Synthesizing Causal Evidence in a Distributed Research Network

Description

Routines for combining causal effect estimates and study diagnostics across multiple data sites in a distributed study, without sharing patient-level data. Allows for normal and non-normal approximations of the data-site likelihood of the effect parameter.

Author(s)

Maintainer: Martijn Schuemie schuemie@ohdsi.org

Authors:

• Marc A. Suchard msuchard@ucla.edu

• Fan Bu fanbu@ucla.edu

Other contributors:

• Observational Health Data Science and Informatics [copyright holder]

See Also

Useful links:

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

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

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

Approximate Bayesian posterior for hierarchical Normal model

Description

Approximate a Bayesian posterior from a set ofCyclops likelihood profiles under a hierarchical normal model using the Markov chain Monte Carlo engine BEAST.

Usage

approximateHierarchicalNormalPosterior(
  likelihoodProfiles,
  chainLength = 1100000,
  burnIn = 1e+05,
  subSampleFrequency = 100,
  effectPriorMean = 0,
  effectPriorSd = 0.5,
  nu0 = 1,
  sigma0 = 1,
  effectStartingValue = 0,
  precisionStartingValue = 1,
  seed = 1
)

Arguments

Value

A data frame with the point estimates and 95% credible intervals for the the global and local parameter, as well as the global precision. Attributes of the data frame contain the MCMC trace for diagnostics.

Examples

# TBD

Approximate a likelihood function

Description

Approximate the likelihood function using a parametric (normal, skew-normal, or custom parametric), or grid approximation. The approximation does not reveal person-level information, and can therefore be shared among data sites. When counts are low, a normal approximation might not be appropriate.

Usage

approximateLikelihood(
  cyclopsFit,
  parameter = 1,
  approximation = "grid with gradients",
  bounds = c(log(0.1), log(10))
)

Arguments

Value

A vector of parameters of the likelihood approximation.

See Also

computeConfidenceInterval, computeFixedEffectMetaAnalysis, computeBayesianMetaAnalysis

Examples

# Simulate some data for this example:
populations <- simulatePopulations()

cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
  data = populations[[1]],
  modelType = "cox"
)
cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
approximation <- approximateLikelihood(cyclopsFit, "x")
approximation

# (Estimates in this example will vary due to the random simulation)

Approximate simple Bayesian posterior

Description

Approximate a Bayesian posterior from a Cyclops likelihood profile and normal prior using the Markov chain Monte Carlo engine BEAST.

Usage

approximateSimplePosterior(
  likelihoodProfile,
  chainLength = 1100000,
  burnIn = 1e+05,
  subSampleFrequency = 100,
  priorMean = 0,
  priorSd = 0.5,
  startingValue = 0,
  seed = 1
)

Arguments

Value

A data frame with the point estimates and 95% credible intervals for the regression parameter. Attributes of the data frame contain the MCMC trace for diagnostics.

Examples

# Simulate some data for this example:
population <- simulatePopulations(createSimulationSettings(nSites = 1))[[1]]

# Fit a Cox regression at each data site, and approximate likelihood function:
cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
  data = population,
  modelType = "cox"
)
cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
likelihoodProfile <- approximateLikelihood(cyclopsFit, parameter = "x", approximation = "grid")

# Run MCMC
mcmcTraces <- approximateSimplePosterior(
  likelihoodProfile = likelihoodProfile,
  priorMean = 0, priorSd = 100
)

# Report posterior expectation
mean(mcmcTraces$theta)

# (Estimates in this example will vary due to the random simulation)

Bias Correction with Inference

Description

Perform Bayesian posterior inference regarding an outcome of interest with bias correction using negative control analysis. There is an option to not perform bias correction so that un-corrected results can be obtained.

Usage

biasCorrectionInference(
  likelihoodProfiles,
  ncLikelihoodProfiles = NULL,
  biasDistributions = NULL,
  priorMean = 0,
  priorSd = 1,
  numsamps = 10000,
  thin = 10,
  doCorrection = TRUE,
  seed = 1,
  ...
)

Arguments

Value

A dataframe with five columns, including posterior median and mean of log RR effect size estimates, 95% credible intervals (ci95Lb and ci95Ub), posterior probability that log RR > 0 (p1), and the period or group ID (Id).

It is accompanied by the following attributes:

• samplesCorrected: all MCMC samples for the bias corrected log RR effect size estimate.

• samplesRaw: all MCMC samples for log RR effect size estimate, without bias correction.

• biasDistributions: the learned empirical bias distribution from negative control analysis.

• summaryRaw: a summary dataframe (same format as in the main result) without bias correction.

• corrected: a logical flag indicating if bias correction has been performed; = TRUE if doCorrection = TRUE.

See Also

approximateSimplePosterior, fitBiasDistribution

Examples

# load example data
data("ncLikelihoods")
data("ooiLikelihoods")

# perform sequential analysis with bias correction, using the t model
# NOT RUN
# bbcResults = biasCorrectionInference(ooiLikelihoods,
#                                      ncLikelihoodProfiles = ncLikelihoods,
#                                      robust = TRUE,
#                                      seed = 42)

# check out analysis summary
# bbcResults

Build a list of references that map likelihood names to integer labels for later use

Description

Build a list of references that map likelihood names to integer labels for later use

Usage

buildLabelReferences(data)

Arguments

Examples

data("likelihoodProfileLists")
refLabs <- buildLabelReferences(likelihoodProfileLists)

Compute a Bayesian random-effects meta-analysis

Description

Compute a Bayesian meta-analysis using the Markov chain Monte Carlo (MCMC) engine BEAST. A normal and half-normal prior are used for the mu and tau parameters, respectively, with standard deviations as defined by the priorSd argument.

Usage

computeBayesianMetaAnalysis(
  data,
  chainLength = 1100000,
  burnIn = 1e+05,
  subSampleFrequency = 100,
  priorSd = c(2, 0.5),
  alpha = 0.05,
  robust = FALSE,
  df = 4,
  seed = 1,
  showProgressBar = TRUE
)

Arguments

Value

A data frame with the point estimates and 95% credible intervals for the mu and tau parameters (the mean and standard deviation of the distribution from which the per-site effect sizes are drawn). Attributes of the data frame contain the MCMC trace and the detected approximation type.

See Also

approximateLikelihood, computeFixedEffectMetaAnalysis

Examples

# Simulate some data for this example:
populations <- simulatePopulations()

# Fit a Cox regression at each data site, and approximate likelihood function:
fitModelInDatabase <- function(population) {
  cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
    data = population,
    modelType = "cox"
  )
  cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
  approximation <- approximateLikelihood(cyclopsFit, parameter = "x", approximation = "custom")
  return(approximation)
}
approximations <- lapply(populations, fitModelInDatabase)
approximations <- do.call("rbind", approximations)

# At study coordinating center, perform meta-analysis using per-site approximations:
estimate <- computeBayesianMetaAnalysis(approximations)
estimate

# (Estimates in this example will vary due to the random simulation)

Compute the point estimate and confidence interval given a likelihood function approximation

Description

Compute the point estimate and confidence interval given a likelihood function approximation

Usage

computeConfidenceInterval(approximation, alpha = 0.05)

Arguments

Details

Compute the point estimate and confidence interval given a likelihood function approximation.

Value

A data frame containing the point estimate, and upper and lower bound of the confidence interval.

Examples

# Simulate some data for this example:
populations <- simulatePopulations()

cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
  data = populations[[1]],
  modelType = "cox"
)
cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
approximation <- approximateLikelihood(cyclopsFit, "x")
computeConfidenceInterval(approximation)

Compute a fixed-effect meta-analysis

Description

Compute a fixed-effect meta-analysis using a choice of various likelihood approximations.

Usage

computeFixedEffectMetaAnalysis(data, alpha = 0.05)

Arguments

Value

The meta-analytic estimate, expressed as the point estimate hazard ratio (rr), its 95 percent confidence interval (lb, ub), as well as the log of the point estimate (logRr), and the standard error (seLogRr).

See Also

approximateLikelihood, computeBayesianMetaAnalysis

Examples

# Simulate some data for this example:
populations <- simulatePopulations()

# Fit a Cox regression at each data site, and approximate likelihood function:
fitModelInDatabase <- function(population) {
  cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
    data = population,
    modelType = "cox"
  )
  cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
  approximation <- approximateLikelihood(cyclopsFit, parameter = "x", approximation = "custom")
  return(approximation)
}
approximations <- lapply(populations, fitModelInDatabase)
approximations <- do.call("rbind", approximations)

# At study coordinating center, perform meta-analysis using per-site approximations:
computeFixedEffectMetaAnalysis(approximations)

# (Estimates in this example will vary due to the random simulation)

Compute a Bayesian random-effects hierarchical meta-analysis

Description

Compute a Bayesian hierarchical meta-analysis (two-level model) to learn the global effect with bias correction via negative control outcomes analysis. Bayesian inference is performed using the Markov chain Monte Carlo (MCMC) engine BEAST. Normal priors are used for the global effect, outcome-specific effects, and data-source-specific effects; a half normal prior is used for the standard deviation; a gamma prior is used for the precision parameters.

Usage

computeHierarchicalMetaAnalysis(
  data,
  settings = generateBayesianHMAsettings(),
  alpha = 0.05,
  seed = 1,
  showProgressBar = TRUE
)

Arguments

Value

A data frame with the point estimates, 95% credible intervals and sample standard errors for the (de-biased) global main effect, the average outcome effect, the average data source effect, and precision of random errors. Attributes of the data frame contain the MCMC trace and the detected approximation type.

See Also

approximateLikelihood, computeBayesianMetaAnalysis

Examples

data("hmaLikelihoodList")
estimates <- EvidenceSynthesis::computeHierarchicalMetaAnalysis(
  data = hmaLikelihoodList,
  seed = 666
)

Construct DataModel objects from approximate likelihood or profile likelihood data

Description

Construct DataModel objects from approximate likelihood or profile likelihood data

Usage

constructDataModel(data, labelReferences = NULL)

Arguments

Examples

data("likelihoodProfileLists")
dataModel <- constructDataModel(likelihoodProfileLists[[1]])

Create likelihood approximations from individual-trajectory data

Description

Create likelihood approximations from individual-trajectory data

Usage

createApproximations(populations, approximation)

Arguments

Create SCCS simulation settings

Description

Create an object specifying a simulation for the Self-Controlled Case Series (SCCS).

Usage

createSccsSimulationSettings(
  nSites = 5,
  n = 10000,
  atRiskTimeFraction = 0.1,
  timePartitions = 24,
  timeCovariates = 5,
  timeEffectSize = log(2),
  minBackgroundRate = 0.001,
  maxBackgroundRate = 0.01,
  rateRatio = 2,
  randomEffectSd = 0
)

Arguments

Value

An object of type simulationSccsSettings, to be used in the simulatePopulations() function.

See Also

simulatePopulations

Examples

settings <- createSccsSimulationSettings(nSites = 1, rateRatio = 2)
populations <- simulatePopulations(settings)

# Fit a SCCS regression for the simulated data site:
cyclopsData <- Cyclops::createCyclopsData(
  y ~ a + x1 + x2 + x3 + x4 + x5 + strata(stratumId) + offset(log(time)),
  data = populations[[1]],
  modelType = "cpr"
)
cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
coef(cyclopsFit)

# (Estimates in this example will vary due to the random simulation)

Create simulation settings

Description

Create an object specifying a simulation. Currently only Cox proportional hazard models are supported.

Usage

createSimulationSettings(
  nSites = 5,
  n = 10000,
  treatedFraction = 0.2,
  nStrata = 10,
  minBackgroundHazard = 2e-07,
  maxBackgroundHazard = 2e-05,
  hazardRatio = 2,
  randomEffectSd = 0,
  siteEffects = 0
)

Arguments

Value

An object of type simulationSettings, to be used in the simulatePopulations() function.

See Also

simulatePopulations

Examples

settings <- createSimulationSettings(nSites = 1, hazardRatio = 2)
populations <- simulatePopulations(settings)

# Fit a Cox regression for the simulated data site:
cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
  data = populations[[1]],
  modelType = "cox"
)
cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
coef(cyclopsFit)

# (Estimates in this example will vary due to the random simulation)

A custom function to approximate a log likelihood function

Description

A custom function to approximate a log likelihood function

Usage

customFunction(x, mu, sigma, gamma)

Arguments

Details

A custom parametric function designed to approximate the shape of the Cox log likelihood function. When gamma = 0 this function is the normal distribution.

Value

The approximate log likelihood for the given x.

Examples

customFunction(x = 0:3, mu = 0, sigma = 1, gamma = 0)

Detect the type of likelihood approximation based on the data format

Description

Detect the type of likelihood approximation based on the data format

Usage

detectApproximationType(data, verbose = TRUE)

Arguments

Value

A character vector with one of the following values: "normal", "custom", "skew normal", "pooled", "grid", or "adaptive grid".

Examples

detectApproximationType(data.frame(logRr = 1, seLogRr = 0.1))

Compute source-specific biases and bias-corrected estimates from hierarchical meta analysis results

Description

Extract source-specific biases and obtain bias-corrected estimates for each data source, given the results from computeHierarchicalMetaAnalysis().

Usage

extractSourceSpecificEffects(estimates, alpha = 0.05)

Arguments

Value

A data frame with point estimates, 95% credible intervals and sample standard errors for the effect size after bias correction within each data source.

See Also

computeHierarchicalMetaAnalysis

Fit Bias Distribution

Description

Learn an empirical distribution on estimation bias by simultaneously analyzing a large set of negative control outcomes by a Bayesian hierarchical model through MCMC. Analysis is based on a list of extracted likelihood profiles.

Usage

fitBiasDistribution(
  likelihoodProfiles,
  priorSds = c(2, 0.5),
  numsamps = 10000,
  thin = 10,
  minNCs = 5,
  robust = FALSE,
  df = 4,
  seed = 1
)

Arguments

Value

A dataframe with three columns and numsamps number of rows. Column mean includes MCMC samples for the average bias, scale for the sd/scale parameter, and bias for predictive samples of the bias.

See Also

computeBayesianMetaAnalysis

Examples

# load example data
data("ncLikelihoods")

# fit a bias distributions by analyzing a set of negative control outcomes
# for example, for the 5th analysis period, and using the t model
# NOT RUN
# biasDistribution = fitBiasDistribution(ncLikelihoods[[5]], robust = TRUE)

Generate settings for the Bayesian random-effects hierarchical meta-analysis model

Description

This function generates a settings list for fitting a Bayesian hierarchical meta-analysis model. See computeHierarchicalMetaAnalysis() for more details.

Usage

generateBayesianHMAsettings(
  primaryEffectPriorStd = 1,
  secondaryEffectPriorStd = 1,
  globalExposureEffectPriorMean = c(0),
  globalExposureEffectPriorStd = c(2),
  primaryEffectPrecisionPrior = c(1, 1),
  secondaryEffectPrecisionPrior = c(1, 1),
  errorPrecisionPrior = c(1, 1),
  errorPrecisionStartValue = 1,
  includeSourceEffect = TRUE,
  includeExposureEffect = TRUE,
  exposureEffectCount = 1,
  separateExposurePrior = FALSE,
  chainLength = 1100000,
  burnIn = 1e+05,
  subSampleFrequency = 100
)

Arguments

Value

A list with all the settings to use in the computeHierarchicalMetaAnalysis() function.

See Also

computeHierarchicalMetaAnalysis

Cubic Hermite interpolation using both values and gradients to approximate a log likelihood function

Description

Cubic Hermite interpolation using both values and gradients to approximate a log likelihood function

Usage

hermiteInterpolation(x, profile)

Arguments

Details

Performs spline interpolation using cubic Hermite polynomials (Catmull et al. 1974) between the points specified in the profile. We use linear extrapolation outside the points.

Value

The approximate log likelihood for the given x.

References

Catmull, Edwin; Rom, Raphael (1974), "A class of local interpolating splines", in Barnhill, R. E.; Riesenfeld, R. F. (eds.), Computer Aided Geometric Design, New York: Academic Press, pp. 317–326

Examples

profile <- data.frame(point = c(1.1, 2.1), value = c(1, 1), derivative = c(0.1, -0.1))
hermiteInterpolation(x = 0:3, profile = profile)

Example profile likelihoods for hierarchical meta analysis with bias correction

Description

A list that contains profile likelihoods for two negative control outcomes and a synthetic outcome of interest, across four data sources. Each element of the list contains profile likelihoods for one outcome, where each row provides profile likelihood values (over a grid) from one data source.

Usage

hmaLikelihoodList

Format

An objects of class list; the list contains 3 dataframes, where each dataframe includes four rows of likelihood function values corresponding to the points in the column names.

Examples

data("hmaLikelihoodList")
hmaLikEx <- hmaLikelihoodList[[1]]

plot(as.numeric(hmaLikEx[2, ]) ~ as.numeric(names(hmaLikEx)))

A bigger example of profile likelihoods for hierarchical meta analysis with bias correction

Description

A list that contains profile likelihoods for 10 negative control outcomes and an outcome of interest, across data sources. Each element of the list contains a named list of profile likelihoods for one outcome, where each element is a data frame that provides likelihood values over a grid of parameter values, the element name corresponding to data source name.

Usage

likelihoodProfileLists

Format

An objects of class list; the list contains 11 named lists, each list for one outcome. Each list contains data frames that record profile likelihoods from different data sources. The first 10 list corresponds to 10 negative control outcomes, whereas the last list the outcome of interest.

Examples

data("likelihoodProfileLists")
exLP <- likelihoodProfileLists[[1]][[1]]

plot(value ~ point, data = exLP)

Load the Cyclops dynamic C++ library for use in Java

Description

Load the Cyclops dynamic C++ library for Markov chain Monte Carlo (MCMC) engine BEAST sampling.

Usage

loadCyclopsLibraryForJava(
  file = system.file("libs", "Cyclops.so", package = "Cyclops")
)

Arguments

Example profile likelihoods for negative control outcomes

Description

A list that contain profile likelihoods a large set of negative control outcomes. They are extracted from a real-world observational healthcare database, with the likelihoods profiled using adaptive grids using the Cyclops package.

Usage

ncLikelihoods

Format

An object of class list containing 12 lists, where each list includes several dataframes ith column point and value for adaptive grid profile likelihoods.

References

Schuemie et al. (2022). Vaccine safety surveillance using routinely collected healthcare data—an empirical evaluation of epidemiological designs. Frontiers in Pharmacology.

Examples

data("ncLikelihoods")
ncLikEx <- ncLikelihoods[["5"]][[1]]

plot(value ~ point, data = ncLikEx)

Example profile likelihoods for a synthetic outcome of interest

Description

A list that contain profile likelihoods for a synthetic outcome of interest. They are extracted from a real-world observational healthcare database, with the likelihoods profiled using adaptive grids using the Cyclops package.

Usage

ooiLikelihoods

Format

An objects of class list; the list contains 12 lists, where each list includes several dataframes with column point and value for adaptive grid profile likelihoods.

References

Schuemie et al. (2022). Vaccine safety surveillance using routinely collected healthcare data—an empirical evaluation of epidemiological designs. Frontiers in Pharmacology.

Examples

data("ooiLikelihoods")
ooiLikEx <- ooiLikelihoods[["5"]][[1]]

plot(value ~ point, data = ooiLikEx)

Plot bias correction inference

Description

Plot bias correction inference

Usage

plotBiasCorrectionInference(
  bbcResult,
  type = "raw",
  ids = bbcResult$Id,
  limits = c(-3, 3),
  logScale = FALSE,
  numericId = TRUE,
  fileName = NULL
)

Arguments

Details

Plot empirical bias distributions learned from analyzing negative controls.

Value

A ggplot object. Use the ggplot2::ggsave function to save to file.

See Also

biasCorrectionInference

Examples

# Perform sequential analysis using Bayesian bias correction for this example:
data("ncLikelihoods")
data("ooiLikelihoods")
# NOT RUN
# bbcSequential = biasCorrectionInference(ooiLikelihoods, ncLikelihoodProfiles = ncLikelihoods)

# Plot it
# NOT RUN
# plotBiasCorrectionInference(bbcSequential, type = "corrected")

Plot bias distributions

Description

Plot bias distributions

Usage

plotBiasDistribution(
  biasDist,
  limits = c(-2, 2),
  logScale = FALSE,
  numericId = TRUE,
  fileName = NULL
)

Arguments

Details

Plot empirical bias distributions learned from analyzing negative controls.

Value

A ggplot object. Use the ggplot2::ggsave function to save to file.

See Also

fitBiasDistribution, sequentialFitBiasDistribution

Examples

# Fit a bias distribution for this example:
data("ncLikelihoods")
# NOT RUN
# singleBiasDist = fitBiasDistribution(ncLikelihoods[[5]], seed = 1)

# Plot it
# NOT RUN
# plotBiasDistribution(singleBiasDist)

Plot covariate balances

Description

Plots the covariate balance before and after matching for multiple data sources.

Usage

plotCovariateBalances(
  balances,
  labels,
  threshold = 0,
  beforeLabel = "Before matching",
  afterLabel = "After matching",
  fileName = NULL
)

Arguments

Details

Creates a plot showing the covariate balance before and after matching. Balance distributions are displayed as box plots combined with scatterplots.

Value

A Ggplot object. Use the ggplot2::ggsave.

Examples

# Some example data:
balance1 <- data.frame(
  beforeMatchingStdDiff = rnorm(1000, 0.1, 0.1),
  afterMatchingStdDiff = rnorm(1000, 0, 0.01)
)
balance2 <- data.frame(
  beforeMatchingStdDiff = rnorm(1000, 0.2, 0.1),
  afterMatchingStdDiff = rnorm(1000, 0, 0.05)
)
balance3 <- data.frame(
  beforeMatchingStdDiff = rnorm(1000, 0, 0.1),
  afterMatchingStdDiff = rnorm(1000, 0, 0.03)
)
plotCovariateBalances(
  balances = list(balance1, balance2, balance3),
  labels = c("Site A", "Site B", "Site C")
)

Plot empirical null distributions

Description

Plot the empirical null distribution for multiple data sources.

Usage

plotEmpiricalNulls(
  logRr,
  seLogRr,
  labels,
  xLabel = "Relative risk",
  limits = c(0.1, 10),
  showCis = TRUE,
  fileName = NULL
)

Arguments

Details

Creates a plot showing the empirical null distributions. Distributions are shown as mean plus minus one standard deviation, as well as a distribution plot.

Value

A Ggplot object. Use the ggplot2::ggsave() function to save to file.

See Also

EmpiricalCalibration::fitNull, EmpiricalCalibration::fitMcmcNull

Examples

# Some example data:
site1 <- EmpiricalCalibration::simulateControls(n = 50, mean = 0, sd = 0.1, trueLogRr = 0)
site1$label <- "Site 1"
site2 <- EmpiricalCalibration::simulateControls(n = 50, mean = 0.1, sd = 0.2, trueLogRr = 0)
site2$label <- "Site 2"
site3 <- EmpiricalCalibration::simulateControls(n = 50, mean = 0.15, sd = 0.25, trueLogRr = 0)
site3$label <- "Site 3"
sites <- rbind(site1, site2, site3)

plotEmpiricalNulls(logRr = sites$logRr, seLogRr = sites$seLogRr, labels = sites$label)

Plot the likelihood approximation

Description

Plot the likelihood approximation

Usage

plotLikelihoodFit(
  approximation,
  cyclopsFit,
  parameter = "x",
  logScale = TRUE,
  xLabel = "Hazard Ratio",
  limits = c(0.1, 10),
  fileName = NULL
)

Arguments

Details

Plots the (log) likelihood and the approximation of the likelihood. Allows for reviewing the approximation.

Value

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

Examples

# Simulate a single database population:
population <- simulatePopulations(createSimulationSettings(nSites = 1))[[1]]

# Approximate the likelihood:
cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
  data = population,
  modelType = "cox"
)
cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
approximation <- approximateLikelihood(cyclopsFit, parameter = "x", approximation = "custom")

plotLikelihoodFit(approximation, cyclopsFit, parameter = "x")

Plot MCMC trace

Description

Plot MCMC trace

Usage

plotMcmcTrace(
  estimate,
  showEstimate = TRUE,
  dataCutoff = 0.01,
  fileName = NULL
)

Arguments

Details

Plot the samples of the posterior distribution of the mu and tau parameters. Samples are taken using Markov-chain Monte Carlo (MCMC).

Value

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

See Also

computeBayesianMetaAnalysis

Examples

# Simulate some data for this example:
populations <- simulatePopulations()

# Fit a Cox regression at each data site, and approximate likelihood function:
fitModelInDatabase <- function(population) {
  cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
    data = population,
    modelType = "cox"
  )
  cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
  approximation <- approximateLikelihood(cyclopsFit, parameter = "x", approximation = "custom")
  return(approximation)
}
approximations <- lapply(populations, fitModelInDatabase)
approximations <- do.call("rbind", approximations)

# At study coordinating center, perform meta-analysis using per-site approximations:
estimate <- computeBayesianMetaAnalysis(approximations)
plotMcmcTrace(estimate)

Create a forest plot

Description

Creates a forest plot of effect size estimates, including the summary estimate.

Usage

plotMetaAnalysisForest(
  data,
  labels,
  estimate,
  xLabel = "Relative risk",
  summaryLabel = "Summary",
  limits = c(0.1, 10),
  alpha = 0.05,
  showLikelihood = TRUE,
  fileName = NULL
)

Arguments

Details

Creates a forest plot of effect size estimates, including a meta-analysis estimate.

Value

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

Examples

# Simulate some data for this example:
populations <- simulatePopulations()
labels <- paste("Data site", LETTERS[1:length(populations)])

# Fit a Cox regression at each data site, and approximate likelihood function:
fitModelInDatabase <- function(population) {
  cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
    data = population,
    modelType = "cox"
  )
  cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
  approximation <- approximateLikelihood(cyclopsFit, parameter = "x", approximation = "custom")
  return(approximation)
}
approximations <- lapply(populations, fitModelInDatabase)
approximations <- do.call("rbind", approximations)

# At study coordinating center, perform meta-analysis using per-site approximations:
estimate <- computeBayesianMetaAnalysis(approximations)
plotMetaAnalysisForest(approximations, labels, estimate)

# (Estimates in this example will vary due to the random simulation)

Plot MCMC trace for individual databases

Description

Plot MCMC trace for individual databases

Usage

plotPerDbMcmcTrace(
  estimate,
  showEstimate = TRUE,
  dataCutoff = 0.01,
  fileName = NULL
)

Arguments

Details

Plot the samples of the posterior distribution of the theta parameter (the estimated log hazard ratio) at each site. Samples are taken using Markov-chain Monte Carlo (MCMC).

Value

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

See Also

computeBayesianMetaAnalysis

Examples

# Simulate some data for this example:
populations <- simulatePopulations()

# Fit a Cox regression at each data site, and approximate likelihood function:
fitModelInDatabase <- function(population) {
  cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
    data = population,
    modelType = "cox"
  )
  cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
  approximation <- approximateLikelihood(cyclopsFit, parameter = "x", approximation = "custom")
  return(approximation)
}
approximations <- lapply(populations, fitModelInDatabase)
approximations <- do.call("rbind", approximations)

# At study coordinating center, perform meta-analysis using per-site approximations:
estimate <- computeBayesianMetaAnalysis(approximations)
plotPerDbMcmcTrace(estimate)

Plot posterior density per database

Description

Plot posterior density per database

Usage

plotPerDbPosterior(
  estimate,
  showEstimate = TRUE,
  dataCutoff = 0.01,
  fileName = NULL
)

Arguments

Details

Plot the density of the posterior distribution of the theta parameter (the estimated log hazard ratio) at each site.

Value

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

Examples

# Simulate some data for this example:
populations <- simulatePopulations()

# Fit a Cox regression at each data site, and approximate likelihood function:
fitModelInDatabase <- function(population) {
  cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
    data = population,
    modelType = "cox"
  )
  cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
  approximation <- approximateLikelihood(cyclopsFit, parameter = "x", approximation = "custom")
  return(approximation)
}
approximations <- lapply(populations, fitModelInDatabase)
approximations <- do.call("rbind", approximations)

# At study coordinating center, perform meta-analysis using per-site approximations:
estimate <- computeBayesianMetaAnalysis(approximations)
plotPerDbPosterior(estimate)

Plot posterior density

Description

Plot posterior density

Usage

plotPosterior(
  estimate,
  showEstimate = TRUE,
  dataCutoff = 0.01,
  fileName = NULL
)

Arguments

Details

Plot the density of the posterior distribution of the mu and tau parameters.

Value

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

See Also

computeBayesianMetaAnalysis

Examples

# Simulate some data for this example:
populations <- simulatePopulations()

# Fit a Cox regression at each data site, and approximate likelihood function:
fitModelInDatabase <- function(population) {
  cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
    data = population,
    modelType = "cox"
  )
  cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
  approximation <- approximateLikelihood(cyclopsFit, parameter = "x", approximation = "custom")
  return(approximation)
}
approximations <- lapply(populations, fitModelInDatabase)
approximations <- do.call("rbind", approximations)

# At study coordinating center, perform meta-analysis using per-site approximations:
estimate <- computeBayesianMetaAnalysis(approximations)
plotPosterior(estimate)

Plot the propensity score distribution

Description

Plot the propensity score distribution

Usage

plotPreparedPs(
  preparedPsPlots,
  labels,
  treatmentLabel = "Target",
  comparatorLabel = "Comparator",
  fileName = NULL
)

Arguments

Value

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

See Also

preparePsPlot

Examples

# Simulate some data for this example:
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, ]
preparedPlot <- preparePsPlot(data)

# Just reusing the same data three times for demonstration purposes:
preparedPsPlots <- list(preparedPlot, preparedPlot, preparedPlot)
labels <- c("Data site A", "Data site B", "Data site C")

plotPreparedPs(preparedPsPlots, labels)

Prepare to plot the propensity score distribution

Description

Prepare to plot the propensity (or preference) score distribution. It computes the distribution, so the output does not contain person-level data.

Usage

preparePsPlot(data, unfilteredData = NULL, scale = "preference")

Arguments

Details

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

• treatment (integer): Column indicating whether the person is in the treated (1) or comparator (0) group. - propensityScore (numeric): Propensity score.

Value

A data frame describing the propensity score (or preference score) distribution at 100 equally-spaced points.

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

See Also

plotPreparedPs

Examples

# Simulate some data for this example:
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, ]

preparedPlot <- preparePsPlot(data)

Prepare SCCS interval data for pooled analysis

Description

Prepare SCCS interval data for pooled analysis

Usage

prepareSccsIntervalData(sccsIntervalData, covariateId)

Arguments

Value

A tibble that can be used in the computeBayesianMetaAnalysis() function.

Fit Bias Distribution Sequentially or in Groups

Description

Learn empirical bias distributions sequentially or in groups; for each sequential step or analysis group, bias distributions is learned by by simultaneously analyzing a large set of negative control outcomes by a Bayesian hierarchical model through MCMC.

Usage

sequentialFitBiasDistribution(LikelihoodProfileList, ...)

Arguments

Value

A (long) dataframe with four columns. Column mean includes MCMC samples for the average bias, scale for the sd/scale parameter, bias for predictive samples of the bias, and Id for the period ID or group ID.

See Also

fitBiasDistribution, computeBayesianMetaAnalysis

Examples

# load example data
data("ncLikelihoods")

# fit bias distributions over analysis periods
# NOT RUN
# biasDistributions = sequentialFitBiasDistribution(ncLikelihoods, seed = 42)

Simulate survival data across a federated data network, with negative control outcomes as well.

Description

A function to simulate patient-level survival data for a hypothetical exposure, with simulated bias and data-source-specific random effects. Patient-level data for negative control outcomes are simulated as well to reflect systematic error.

Usage

simulateMetaAnalysisWithNegativeControls(
  meanExposureEffect = log(2),
  meanBias = 0.5,
  biasStd = 0.2,
  meanSiteEffect = 0,
  siteEffectStd = 0.1,
  mNegativeControls = 10,
  nSites = 10,
  sitePop = 2000,
  seed = 42,
  ...
)

Arguments

See Also

computeHierarchicalMetaAnalysis

Simulate survival data for multiple databases

Description

Simulate survival data for multiple databases

Usage

simulatePopulations(settings = createSimulationSettings())

Arguments

Value

A object of class simulation, which is a list of population data frames. Depending on the type of simulation, the data frames have different columns: Cox simulations will have the columns rowId, stratumId, x, time, and y. SCCS simulations will have the columns stratumId, a, x1...xN, time, and y.

Examples

settings <- createSimulationSettings(nSites = 1, hazardRatio = 2)
populations <- simulatePopulations(settings)

# Fit a Cox regression for the simulated data site:
cyclopsData <- Cyclops::createCyclopsData(Surv(time, y) ~ x + strata(stratumId),
  data = populations[[1]],
  modelType = "cox"
)
cyclopsFit <- Cyclops::fitCyclopsModel(cyclopsData)
coef(cyclopsFit)

# (Estimates in this example will vary due to the random simulation)

The skew normal function to approximate a log likelihood function

Description

The skew normal function to approximate a log likelihood function

Usage

skewNormal(x, mu, sigma, alpha)

Arguments

Details

The skew normal function. When alpha = 0 this function is the normal distribution.

Value

The approximate log likelihood for the given x.

References

Azzalini, A. (2013). The Skew-Normal and Related Families. Institute of Mathematical Statistics Monographs. Cambridge University Press.

Examples

skewNormal(x = 0:3, mu = 0, sigma = 1, alpha = 0)

Utility function to summarize MCMC samples (posterior mean, median, HDI, std, etc.)

Description

Utility function to summarize MCMC samples (posterior mean, median, HDI, std, etc.)

Usage

summarizeChain(chain, alpha = 0.05)

Arguments

Determine if Java virtual machine supports Java

Description

Tests Java virtual machine (JVM) java.version system property to check if version >= 8.

Usage

supportsJava8()

Value

Returns TRUE if JVM supports Java >= 8.

Examples

supportsJava8()