Package {PheValuator}

PheValuator: Rapid Phenotype Evaluation

Description

Evaluates phenotype algorithms by developing a diagnostic prediction model using a set of noisy positives and noisy negatives. It can then apply the model to a large cohort to create a set of subjects each with a predicted probability for the health outcome of interest. This cohort can then be used to evaluate phenotype algorithms through the calculation of the necessary performance characteristics - sensitivity, specificity, and positive and negative predictive value. Swerdel (2022) doi:10.1016/j.jbi.2022.104177 Swerdel (2019) doi:10.1016/j.jbi.2019.103258

Author(s)

Maintainer: William J. O'Brien wobrien8@its.jnj.com

Authors:

• William J. O'Brien wobrien8@its.jnj.com

• Joel Swerdel jswerdel@its.jnj.com

• Martijn Schuemie schuemie@ohdsi.org

See Also

Useful links:

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

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

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

Compute performance metrics based on a 2-by-2 counts table

Description

Compute performance metrics based on a 2-by-2 counts table

Usage

computePerformanceMetricsFromCounts(counts)

Arguments

Value

A tibble with the statistics metrics added to the counts table.

Examples

counts <- tibble::tibble(
  truePositives = 120,
  trueNegatives = 800,
  falsePositives = 30,
  falseNegatives = 50,
  cutPoint = "EV"
)
computePerformanceMetricsFromCounts(counts)

Create a parameter object for the function createEvaluationCohort

Description

Create a parameter object for the function createEvaluationCohort

Usage

createCreateEvaluationCohortArgs(
  xSpecCohortId,
  daysFromxSpec = 0,
  xSensCohortId = prevalenceCohortId,
  prevalenceCohortId,
  caseCohortId = prevalenceCohortId,
  caseFirstOccurrenceOnly = TRUE,
  xSpecCohortSize = 5000,
  covariateSettings = createDefaultCovariateSettings(excludedCovariateConceptIds = c(),
    addDescendantsToExclude = TRUE),
  modelPopulationCohortId = 0,
  modelPopulationCohortIdStartDay = 0,
  modelPopulationCohortIdEndDay = 0,
  inclusionEvaluationCohortId = 0,
  inclusionEvaluationDaysFromStart = 0,
  inclusionEvaluationDaysFromEnd = 0,
  duringInclusionEvaluationOnly = FALSE,
  exclusionEvaluationCohortId = 0,
  exclusionEvaluationDaysFromStart = 0,
  exclusionEvaluationDaysFromEnd = 0,
  minimumOffsetFromStart = 0,
  minimumOffsetFromEnd = 30,
  modelBaseSampleSize = 25000,
  baseSampleSize = 2e+06,
  lowerAgeLimit = 0,
  upperAgeLimit = 120,
  visitLength = 0,
  visitType = c(9201, 9202, 9203, 581477, 262),
  gender = c(8507, 8532),
  race = 0,
  ethnicity = 0,
  startDate = "19001010",
  endDate = "21000101",
  falsePositiveNegativeSubjects = 10,
  modelId = "main",
  evaluationCohortId = "main",
  randomVisitTable = "",
  excludeModelFromEvaluation = FALSE,
  removeSubjectsWithFutureDates = TRUE,
  saveEvaluationCohortPlpData = FALSE
)

Arguments

Details

Create an object defining the parameter values.

Value

A list of class "args" containing all the provided parameters. This object is used as an argument to the createEvaluationCohort function.

Examples

evalCohortArgs <- createCreateEvaluationCohortArgs(
  xSpecCohortId = 1,
  prevalenceCohortId = 3
)

Create the default covariate settings

Description

Create the default covariate settings for acute or chronic diseases

Usage

createDefaultCovariateSettings(
  excludedCovariateConceptIds = c(),
  includedCovariateIds = c(),
  includedCovariateConceptIds = c(),
  addDescendantsToExclude = FALSE,
  startDayWindow1 = 0,
  endDayWindow1 = 9999,
  startDayWindow2 = NULL,
  endDayWindow2 = NULL,
  startDayWindow3 = NULL,
  endDayWindow3 = NULL
)

Arguments

Details

Function to create the default covariate settings for acute or chronic diseases

Value

A list containing one or more covariate settings objects from the FeatureExtraction package. If only the first time window is specified, returns a list with one element. If additional time windows are specified, returns a list with multiple elements.

Examples

covSettings <- createDefaultCovariateSettings(
  excludedCovariateConceptIds = c(201826, 44786627),
  addDescendantsToExclude = TRUE
)

Create the evaluation cohort

Description

Create the evaluation cohort

Usage

createEvaluationCohort(
  connectionDetails,
  oracleTempSchema = NULL,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  phenotype,
  analysisName,
  runDateTime,
  databaseId,
  xSpecCohortId,
  daysFromxSpec = 0,
  xSensCohortId,
  prevalenceCohortId,
  caseCohortId,
  caseFirstOccurrenceOnly,
  xSpecCohortSize = 5000,
  cdmDatabaseSchema,
  cohortDatabaseSchema,
  cohortTable,
  workDatabaseSchema,
  covariateSettings = createDefaultCovariateSettings(excludedCovariateConceptIds = c(),
    addDescendantsToExclude = TRUE),
  modelPopulationCohortId = 0,
  modelPopulationCohortIdStartDay = 0,
  modelPopulationCohortIdEndDay = 0,
  inclusionEvaluationCohortId = 0,
  inclusionEvaluationDaysFromStart = 0,
  inclusionEvaluationDaysFromEnd = 0,
  duringInclusionEvaluationOnly = FALSE,
  exclusionEvaluationCohortId = 0,
  exclusionEvaluationDaysFromStart = 0,
  exclusionEvaluationDaysFromEnd = 0,
  priorModelToUse = NULL,
  minimumOffsetFromStart = 365,
  minimumOffsetFromEnd = 365,
  modelBaseSampleSize = 25000,
  baseSampleSize = 2e+06,
  lowerAgeLimit = 0,
  upperAgeLimit = 120,
  visitLength = 0,
  visitType = c(9201, 9202, 9203, 262, 581477),
  gender = c(8507, 8532),
  race = 0,
  ethnicity = 0,
  startDate = "19001010",
  endDate = "21000101",
  falsePositiveNegativeSubjects = 10,
  cdmVersion = "5",
  outFolder,
  exportFolder,
  modelId = "main",
  evaluationCohortId = "main",
  excludeModelFromEvaluation = FALSE,
  randomVisitTable = "",
  removeSubjectsWithFutureDates = TRUE,
  saveEvaluationCohortPlpData = FALSE
)

Arguments

Details

Fits a diagnostic prediction model, and uses it to create an evaluation cohort with probabilities for the health outcome of interest.

Value

No return value, called for side effects. Creates database tables and output files containing the predictive model and evaluation cohort data with predicted probabilities for the health outcome.

Examples

## Not run: 
connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "postgresql",
  server = "myserver",
  user = "user",
  password = "password"
)
createEvaluationCohort(
  connectionDetails = connectionDetails,
  phenotype = "Diabetes",
  analysisName = "Main",
  runDateTime = format(Sys.time(), "%b %d %Y %X"),
  databaseId = "myDB",
  xSpecCohortId = 1,
  xSensCohortId = 2,
  prevalenceCohortId = 3,
  caseCohortId = 3,
  caseFirstOccurrenceOnly = TRUE,
  cdmDatabaseSchema = "cdm.dbo",
  cohortDatabaseSchema = "results.dbo",
  cohortTable = "cohort",
  workDatabaseSchema = "scratch.dbo",
  outFolder = tempdir(),
  exportFolder = file.path(tempdir(), "export")
)

## End(Not run)

Create a PheValuator analysis specification

Description

Create a PheValuator analysis specification

Usage

createPheValuatorAnalysis(
  analysisId,
  description,
  createEvaluationCohortArgs,
  testPhenotypeAlgorithmArgs
)

Arguments

Details

Create a set of analysis choices, to be used with the runPheValuatorAnalyses function.

Value

A list object of class "pheValuatorAnalysis" containing the analysis specification. Includes the analysis ID, description, and argument specifications for creating the evaluation cohort and testing the phenotype algorithm.

Examples

evalCohortArgs <- createCreateEvaluationCohortArgs(
  xSpecCohortId = 1,
  xSensCohortId = 2,
  prevalenceCohortId = 3
)
testArgs <- createTestPhenotypeAlgorithmArgs(
  phenotypeCohortId = 10
)
analysis <- createPheValuatorAnalysis(
  analysisId = 1,
  description = "Main analysis",
  createEvaluationCohortArgs = evalCohortArgs,
  testPhenotypeAlgorithmArgs = testArgs
)

Create a parameter object for the function testPhenotypeAlgorithm

Description

Create a parameter object for the function testPhenotypeAlgorithm

Usage

createTestPhenotypeAlgorithmArgs(
  cutPoints = c("EV"),
  phenotypeCohortId,
  washoutPeriod = 0,
  splayPrior = 7,
  splayPost = 7
)

Arguments

Details

Create an object defining the parameter values.

Value

A list object of class "args" containing all the provided parameters. This object is used as an argument to the testPhenotypeAlgorithm function.

Examples

testArgs <- createTestPhenotypeAlgorithmArgs(
  phenotypeCohortId = 10,
  cutPoints = c("EV", "0.5")
)

Load a list of phevaluatorAnalysis from file

Description

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

Usage

loadPheValuatorAnalysisList(file)

Arguments

Value

A list of objects of type pheValuatorAnalysis.

Examples

## Not run: 
analysisList <- loadPheValuatorAnalysisList(file = "analysisList.json")

## End(Not run)

Run a list of analyses

Description

Run a list of analyses

Usage

runPheValuatorAnalyses(
  phenotype,
  cohortDefinitionSet = data.frame(),
  analysisName = "Main",
  runDateTime = format(Sys.time(), "%b %d %Y %X"),
  connectionDetails,
  oracleTempSchema = NULL,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cdmDatabaseSchema,
  cohortDatabaseSchema = cdmDatabaseSchema,
  cohortTable = "cohort",
  workDatabaseSchema = cdmDatabaseSchema,
  databaseId = cdmDatabaseSchema,
  cdmVersion = 5,
  outputFolder,
  priorModelToUse = NULL,
  pheValuatorAnalysisList
)

Arguments

Details

Run a list of analyses.

Value

A data frame specifying where the constructed evaluation cohort and phenotype evaluation results can be found in the local file system.

Examples

## Not run: 
connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "postgresql",
  server = "myserver",
  user = "user",
  password = "password"
)
analysisList <- list(
  createPheValuatorAnalysis(
    analysisId = 1,
    description = "Main analysis",
    createEvaluationCohortArgs = createCreateEvaluationCohortArgs(
      xSpecCohortId = 1,
      prevalenceCohortId = 3
    ),
    testPhenotypeAlgorithmArgs = createTestPhenotypeAlgorithmArgs(
      phenotypeCohortId = 10
    )
  )
)
runPheValuatorAnalyses(
  phenotype = "Diabetes",
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = "cdm.dbo",
  outputFolder = tempdir(),
  pheValuatorAnalysisList = analysisList
)

## End(Not run)

Save a list of phevaluatorAnalysis to file

Description

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

Usage

savePheValuatorAnalysisList(pheValuatorAnalysisList, file)

Arguments

Value

No return value, called for side effects. Writes a JSON file containing the analysis list to the specified file path.

Examples

## Not run: 
# Requires pre-existing analysis list object; example usage:
# savePheValuatorAnalysisList(pheValuatorAnalysisList = myAnalysisList,
#                             file = file.path(tempdir(), "analysisList.json"))

## End(Not run)

Summarize results of PheValuator analyses

Description

Summarize results of PheValuator analyses

Usage

summarizePheValuatorAnalyses(referenceTable, outputFolder)

Arguments

Value

A data frame of results.

Examples

## Not run: 
refTable <- runPheValuatorAnalyses(
  phenotype = "Diabetes",
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = "cdm.dbo",
  outputFolder = tempdir(),
  pheValuatorAnalysisList = analysisList
)
results <- summarizePheValuatorAnalyses(refTable, outputFolder = tempdir())

## End(Not run)

Test phenotype algorithms

Description

Test phenotype algorithms

Usage

testPhenotypeAlgorithm(
  phenotype,
  analysisName,
  runDateTime,
  connectionDetails,
  cutPoints = c("EV"),
  outFolder,
  exportFolder,
  evaluationCohortId = "main",
  phenotypeCohortId,
  cdmDatabaseSchema,
  databaseId,
  cohortDatabaseSchema,
  cohortTable,
  washoutPeriod = 0,
  splayPrior = 7,
  splayPost = 7
)

Arguments

Details

This function will perform the phenotype algorithm evaluation using the evaluation cohort returned from createEvalCohort and the phenotype algorithm cohort specified

Value

A dataframe with the results from the phenotype algorithm evaluation.

If 0.5 is included as a cutpoint, the data frame will have an attribute called 'misses', a dataframe with a sample of subject ids for TPs, FPs, TNs, and FNs for the 50 percent and over prediction threshold.

Examples

## Not run: 
connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "postgresql",
  server = "myserver",
  user = "user",
  password = "password"
)
results <- testPhenotypeAlgorithm(
  phenotype = "Diabetes",
  analysisName = "Main",
  runDateTime = format(Sys.time(), "%b %d %Y %X"),
  connectionDetails = connectionDetails,
  cutPoints = c("EV", "0.5"),
  outFolder = tempdir(),
  exportFolder = file.path(tempdir(), "export"),
  phenotypeCohortId = 10,
  cdmDatabaseSchema = "cdm.dbo",
  databaseId = "myDB",
  cohortDatabaseSchema = "results.dbo",
  cohortTable = "cohort"
)

## End(Not run)