Package 'CohortGenerator'

Description

Given a subset definition and cohort definition set, this function returns a modified cohortDefinitionSet That contains cohorts that's have parent's contained within the base cohortDefinitionSet

Also adds the columns subsetParent and isSubset that denote if the cohort is a subset and what the parent definition is.

Usage

addCohortSubsetDefinition(
  cohortDefinitionSet,
  cohortSubsetDefintion,
  targetCohortIds = NULL,
  overwriteExisting = FALSE
)

Arguments

Description

Adds a cohort template definition to an existing cohort definition set or creates one if none provided

Usage

addCohortTemplateDefintion(
  cohortDefinitionSet = createEmptyCohortDefinitionSet(),
  cohortTemplateDefintion
)

Arguments

Description

The purpose of this subset recipe is to exclude all individuals if their index aligns with the specified exclusion cohort ids. If the index date of the exclusionCohortIds aligns with the targetCohortIds (or it lies within some relative window of the target cohort start date) then they will be excluded from the resulting sub population.

This may be used in situations where an outcome cohort may contain individuals treated for a target medication, complicating calculation of incidence rates.

Usage

addExcludeOnIndexSubsetDefinition(
  cohortDefinitionSet,
  subsetDefinitionName,
  subsetCohortNameTemplate = "@baseCohortName - @subsetDefinitionName",
  targetCohortIds,
  exclusionCohortIds,
  exclusionWindow = 0,
  subsetDefinitionId,
  cohortCombinationOperator = "any"
)

Arguments

Examples

## Not run: 
library(CohortGenerator)

initialSet <- getCohortDefinitionSet(
  settingsFileName = "testdata/name/Cohorts.csv",
  jsonFolder = "testdata/name/cohorts",
  sqlFolder = "testdata/name/sql/sql_server",
  cohortFileNameFormat = "%s",
  cohortFileNameValue = c("cohortName"),
  packageName = "CohortGenerator",
  verbose = FALSE
)

print(initialSet[, c("cohortId", "cohortName")])

# Subset cohorts 1 & 2 by an "indication" cohort 3:
res <- addExcludeOnIndexSubsetDefinition(
  cohortDefinitionSet = initialSet,
  targetCohortIds = c(1, 2),
  exclusionCohortIds = c(3),
  subsetDefinitionId = 20,
  subsetDefinitioName = "Exclude on index if in cohort 3"
)

print(res[, c("cohortId", "cohortName", "subsetParent", "subsetDefinitionId", "isSubset")])

# Get all subset definitions that were created using the addExcludeOnIndexSubsetDefinition:
subsetDefinitionId <- getExcludeOnIndexSubsetDefinitionIds(res)

# Filter the cohortDefinitionSet to those cohorts defined using an exclusion subset definition:
newCohorts <- res |>
  dplyr::filter(subsetDefinitionId == subsetDefinitionId) |>
  dplyr::select(cohortId, cohortName, subsetParent, isSubset)
print(newCohorts)

## End(Not run)

Description

Utility pattern for creating an indication subset from a set of target cohorts. The approach applies this subset definition to an exposure (target cohort) or set of exposures (multiple target cohorts), requiring the individual to have a history of the indication cohort overlapping the start of the first exposure. The first exposure must have the 'requiredPriorObservationTime' and 'requiredFollowUpTime'. If specified, the first exposure must also fall within the 'studyStartDate' and 'studyEndDate' and also meet the age and gender criteria.

Additionally, the R attribute of "indicationSubsetDefinitions" is attached to the cohort definition set. This can be obtained by calling 'getIndicationSubsetDefinitionIds', which should return the set of subset definition ids that are associated with indications.

Usage

addIndicationSubsetDefinition(
  cohortDefinitionSet,
  targetCohortIds,
  indicationCohortIds,
  subsetDefinitionId,
  subsetDefinitionName,
  subsetCohortNameTemplate = "@baseCohortName - @subsetDefinitionName",
  cohortCombinationOperator = "any",
  lookbackWindowStart = -99999,
  lookbackWindowEnd = 0,
  lookForwardWindowStart = 0,
  lookForwardWindowEnd = 99999,
  genderConceptIds = NULL,
  ageMin = NULL,
  ageMax = NULL,
  studyStartDate = NULL,
  studyEndDate = NULL,
  requiredPriorObservationTime = 365,
  requiredFollowUpTime = 1
)

Arguments

Examples

## Not run: 
library(CohortGenerator)

initialSet <- getCohortDefinitionSet(
  settingsFileName = "testdata/name/Cohorts.csv",
  jsonFolder = "testdata/name/cohorts",
  sqlFolder = "testdata/name/sql/sql_server",
  cohortFileNameFormat = "%s",
  cohortFileNameValue = c("cohortName"),
  packageName = "CohortGenerator",
  verbose = FALSE
)

print(initialSet[, c("cohortId", "cohortName")])

# Subset cohorts 1 & 2 by an "indication" cohort 3:
res <- addIndicationSubsetDefinition(
  cohortDefinitionSet = initialSet,
  targetCohortIds = c(1, 2),
  indicationCohortIds = c(3),
  subsetDefinitionId = 10
)

print(res[, c("cohortId", "cohortName", "subsetParent", "subsetDefinitionId", "isSubset")])

# Get all subset definitions that were created using the addIndicationSubsetDefinition:
subsetDefinitionId <- getIndicationSubsetDefinitionIds(res)

# Filter the cohortDefinitionSet to those cohorts defined using an indication subset definition:
newCohorts <- res |>
  dplyr::filter(subsetDefinitionId == subsetDefinitionId) |>
  dplyr::select(cohortId, cohortName, subsetParent, isSubset)
print(newCohorts)

## End(Not run)

Description

Utility pattern for creating cohort subset definitions as a standard approach for indicated drugs. Restriction subset definitions are twins of indication definitions. They should apply the same core properties to a base exposure cohort (i.e. study dates, required prior observation time, ages, gender) as indications but, crucially, they do not require history of any prior condition(s).

This is useful in the context of comparing drug exposure + indication population, to population as a whole.

The preferred use of this function is to create this in conjunction with the target population.

Usage

addRestrictionSubsetDefinition(
  cohortDefinitionSet,
  targetCohortIds,
  subsetDefinitionId,
  subsetDefinitionName,
  subsetCohortNameTemplate = "@baseCohortName - @subsetDefinitionName",
  genderConceptIds = NULL,
  ageMin = NULL,
  ageMax = NULL,
  studyStartDate = NULL,
  studyEndDate = NULL,
  requiredPriorObservationTime = 365,
  requiredFollowUpTime = 1
)

Arguments

Examples

## Not run: 
library(CohortGenerator)

initialSet <- getCohortDefinitionSet(
  settingsFileName = "testdata/name/Cohorts.csv",
  jsonFolder = "testdata/name/cohorts",
  sqlFolder = "testdata/name/sql/sql_server",
  cohortFileNameFormat = "%s",
  cohortFileNameValue = c("cohortName"),
  packageName = "CohortGenerator",
  verbose = FALSE
)

print(initialSet[, c("cohortId", "cohortName")])

# Restrinct to first occurrence of cohort
res <- addRestrictionSubsetDefinition(
  cohortDefinitionSet = initialSet,
  targetCohortIds = c(1, 2),
  subsetDefinitionId = 20
)

print(res[, c("cohortId", "cohortName", "subsetParent", "subsetDefinitionId", "isSubset")])

# Get all subset definitions that were created using the addRestrictionSubsetDefinition:
subsetDefinitionId <- getRestrictionSubsetDefinitionIds(res)

# Filter the cohortDefinitionSet to those cohorts defined using an restriction subset definition:
newCohorts <- res |>
  dplyr::filter(subsetDefinitionId == subsetDefinitionId) |>
  dplyr::select(cohortId, cohortName, subsetParent, isSubset)
print(newCohorts)

## End(Not run)

Description

This is useful in cases where it is difficult or impossible to define a cohort in Circe. This utility should be used sparingly, but is convenient non-the-less. Note that no checks on this definition occur and, in principle, any sql can be executed. Incremental execution and logging will work. This should also be compatible with other OHDSI packages that use standard cohort tables.

All cohorts should result in standard cohort tables which have the columns:

* cohort_definition_id, * subject_id, * cohort_start_date, * cohort_end_date

As these are requirements of cohorts.

The sql parameters: cohort_table, cohort_database_schema, cdm_database_schema and vocabulary_database_schema should not be specified in the arguments to this function. These cohorts can be serialized with saveCohortDefinitionSet and shared so should not include data source specific content.

Usage

addSqlCohortDefinition(
  cohortDefinitionSet,
  sql,
  cohortId,
  cohortName,
  tanslateSql = TRUE,
  json = NULL,
  ...
)

Arguments

Examples

sql <- "INSERT INTO @cohort_database_schema.@cohort_table
             (cohort_definition_id, subject_id, cohort_start_date, cohort_end_date)
        SELECT 1 as cohort_definition_id,
               person_id as subject_id,
               drug_era_start_date as cohort_start_date,
               drug_era_end_data as cohort_end_date
        FROM @cdm_database_schema.drug_era de
        INNER JOIN @vocabulary_database_schema.concept c on de.drug_concept_id = c.concept_id
        -- Find any matches of drugs named 'asprin' in the drug concept table
        WHERE lower(c.concept_name) like '%asprin%'; "

cohortDefinitionSet <- createEmptyCohortDefinitionSet() |>
  addSqlCohortDefinition(sql = sql, cohortId = 1, cohortName = "my asprin cohort")

Description

This utility function adds the union of any two or more cohort ids to the cohort definition set with a new id and name.

If a name parameter is not provided this will be auto generated as the union of the provided cohort id

Usage

addUnionCohortDefinition(
  cohortDefinitionSet,
  cohortIds,
  cohortName,
  unionCohortId
)

Arguments

Description

This function checks a data.frame to verify it holds the expected format for a cohortDefinitionSet's data types and can optionally fix data types that do not match the specification.

Usage

checkAndFixCohortDefinitionSetDataTypes(
  x,
  fixDataTypes = TRUE,
  emitWarning = FALSE
)

Arguments

Value

Returns a list() of the following form:

list( dataTypesMatch = TRUE/FALSE, x = data.frame() )

dataTypesMatch == TRUE when the supplied data.frame x matches the cohortDefinitionSet specification's data types.

If fixDataTypes == TRUE, x will hold the original data from x with the data types corrected. Otherwise x will hold the original value passed to this function.

Description

Set of subset definitions pretty in print

Active bindings

Methods

Public methods

• CohortSubsetDefinition$print()

• CohortSubsetDefinition$new()

• CohortSubsetDefinition$toList()

• CohortSubsetDefinition$toJSON()

• CohortSubsetDefinition$addSubsetOperator()

• CohortSubsetDefinition$getSubsetQuery()

• CohortSubsetDefinition$getSubsetCohortName()

• CohortSubsetDefinition$setTargetOutputPairs()

• CohortSubsetDefinition$getJsonFileName()

• CohortSubsetDefinition$clone()

Method print()

Usage

CohortSubsetDefinition$print(...)

Arguments

Method new()

Usage

CohortSubsetDefinition$new(definition = NULL)

Arguments

Method toList()

List representation of object to JSON

Usage

CohortSubsetDefinition$toList()

Method toJSON()

json serialized representation of object add Subset Operator

Usage

CohortSubsetDefinition$toJSON()

Method addSubsetOperator()

add subset to class - checks if equivalent id is present Will throw an error if a matching ID is found but reference object is different

Usage

CohortSubsetDefinition$addSubsetOperator(subsetOperator)

Arguments

Method getSubsetQuery()

Returns vector of join, logic, having statements returned by subset operations

Usage

CohortSubsetDefinition$getSubsetQuery(targetOutputPair)

Arguments

Method getSubsetCohortName()

Usage

CohortSubsetDefinition$getSubsetCohortName(
  cohortDefinitionSet,
  targetOutputPair
)

Arguments

Method setTargetOutputPairs()

Usage

CohortSubsetDefinition$setTargetOutputPairs(targetIds)

Arguments

Method getJsonFileName()

Usage

CohortSubsetDefinition$getJsonFileName(
  subsetJsonFolder = "inst/cohort_subset_definitions/"
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CohortSubsetDefinition$clone(deep = FALSE)

Arguments

Description

A subset of type cohort - subset a population to only those contained within defined cohort

Super class

CohortGenerator::SubsetOperator -> CohortSubsetOperator

Active bindings

Methods

Public methods

• CohortSubsetOperator$new()

• CohortSubsetOperator$toList()

• CohortSubsetOperator$getAutoGeneratedName()

• CohortSubsetOperator$clone()

Method new()

Usage

CohortSubsetOperator$new(definition = NULL)

Arguments

Returns

instance of object to List

Method toList()

List representation of object Get auto generated name

Usage

CohortSubsetOperator$toList()

Method getAutoGeneratedName()

name generated from subset operation properties

Usage

CohortSubsetOperator$getAutoGeneratedName()

Returns

character

Method clone()

The objects of this class are cloneable with this method.

Usage

CohortSubsetOperator$clone(deep = FALSE)

Arguments

Description

Class for automating the creation of bulk cohorts

Class for automating the creation of bulk cohorts

Details

This class provides a framework for automating the creation of bulk cohorts by defining template SQL queries and associated callbacks to execute them. This is useful when defining lots of exposure or outcomes for cohorts that are very general in nature. For example, all RxNorm ingredient cohorts, all ATC ingredient cohorts or all SNOMED condition occurrences with > x diagnosis codes.

These cohorts can then be subsetted with common cohort subset operations such as limiting to specific age, gender, or observation criteria, should this be excluded from the cohort definition. However, when applying operations in bulk it may be more efficient to include such definitions within the template sql itself.

This approach is also useful for cohorts that can not based on ATLAS/CirceDefinitions alone.

CURRENTLY NOT SUPPORTED: * Saving definitions that use runtime arguments on a per cdm basis. This creates a challenge for running the same cohort across different databases. Furthermore, saving information within the CDM schema in a shared OHDSI study is not desirable.

Active bindings

Methods

Public methods

• CohortTemplateDefinition$new()

• CohortTemplateDefinition$executeTemplateSql()

• CohortTemplateDefinition$getTemplateReferences()

• CohortTemplateDefinition$getName()

• CohortTemplateDefinition$getId()

• CohortTemplateDefinition$getChecksum()

• CohortTemplateDefinition$toList()

• CohortTemplateDefinition$toJson()

• CohortTemplateDefinition$saveTemplate()

• CohortTemplateDefinition$clone()

Method new()

Usage

CohortTemplateDefinition$new(settings)

Arguments

Method executeTemplateSql()

Usage

CohortTemplateDefinition$executeTemplateSql(
  connection,
  cohortDatabaseSchema,
  cdmDatabaseSchema,
  cohortTableNames,
  vocabularyDatabaseSchema = cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema")
)

Arguments

Method getTemplateReferences()

Returns data.frame of references get the name of the definition

Usage

CohortTemplateDefinition$getTemplateReferences()

Method getName()

Name field get the generated id of the template definition

Usage

CohortTemplateDefinition$getName()

Method getId()

this is not the cohort ids and is based off of the checksum of the template definition get checksum

Usage

CohortTemplateDefinition$getId()

Method getChecksum()

Get the hash of the definition (generated when class is instantiated) to list

Usage

CohortTemplateDefinition$getChecksum()

Method toList()

Used for serializing the definition to json

Usage

CohortTemplateDefinition$toList()

Method toJson()

json serialized form of the template definition save to disk

Usage

CohortTemplateDefinition$toJson()

Method saveTemplate()

Save object to specified json path

Usage

CohortTemplateDefinition$saveTemplate(filePath)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CohortTemplateDefinition$clone(deep = FALSE)

Arguments

Description

This is used as part of the incremental operations to hash a value to store in a record keeping file. This function leverages the md5 hash from the digest package

Usage

computeChecksum(val)

Arguments

Value

Returns a string containing the checksum

Description

Computes a sequential attrition table using the inclusion rule statistics stored in the cohort statistics tables for Circe-based cohorts. For each cohort definition, we report a base cohort entry count (before inclusion rules) and then counts after applying the first k inclusion rules in sequence.

Inclusion rule satisfaction is encoded as a bit mask in inclusionRuleMask. For a rule sequence i, its bit value is 2^i. A row with inclusionRuleMask equal to the sum of the bits indicates which rules were met. To compute the count after the first k rules, we require all first-k bits to be set by checking bitwAnd(inclusionRuleMask, requiredMask) == requiredMask, where requiredMask = 2^k - 1.

Attrition is computed separately for each modeId present in cohortInclusionResult (for example, person-level and event-level).

Usage

computeCohortAttrition(cohortInclusionResult, cohortInclusion)

Arguments

Value

A data.frame with the following columns:

• databaseId: Database identifier.

• cohortDefinitionId: Cohort definition identifier.

• modeId: The mode identifier from cohortInclusionResult.

• cohortEntry: 1 for the base cohort entry count, 0 for rule rows.

• ruleSequence: Inclusion rule sequence (-1 for base row).

• personCount: Count after applying rules.

Description

Template cohort definition for all ATC level 4 class exposures. The cohortId = conceptId * 1000 + 4. The "identifierExpression" can be customized for uniqueness.

Usage

createAtcCohortTemplateDefinition(
  connection,
  identifierExpression = "CAST(concept_id as bigint) * 1000",
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cohortDatabaseSchema,
  nameSuffix = "",
  mergeIngredientEras = TRUE,
  priorObservationPeriod = 365,
  vocabularyDatabaseSchema = cdmDatabaseSchema
)

Arguments

Value

A CohortTemplateDefinition instance

Description

Subset cohorts using specified limit criteria. deprecated This function is deprecated. Please use 'createCohortSubsetOperator()' instead.

Usage

createCohortSubset(...)

Arguments

Description

Create subset definition from subset objects

Usage

createCohortSubsetDefinition(
  name,
  definitionId,
  subsetOperators,
  identifierExpression = NULL,
  subsetCohortNameTemplate = "@baseCohortName - @subsetDefinitionName"
)

Arguments

Description

A definition of subset functions to be applied to a set of cohorts

Usage

createCohortSubsetOperator(
  name = NULL,
  cohortIds,
  cohortCombinationOperator,
  negate,
  windows = list(),
  startWindow = NULL,
  endWindow = NULL
)

Arguments

Value

a CohortSubsetOperator instance

See Also

Other subsets: createDemographicSubsetOperator(), createLimitSubsetOperator()

Description

This function creates an empty cohort table and empty tables for cohort statistics.

Usage

createCohortTables(
  connectionDetails = NULL,
  connection = NULL,
  cohortDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  incremental = FALSE
)

Arguments

Description

construct a cohort template definition

Usage

createCohortTemplateDefintion(
  name,
  templateSql,
  references,
  sqlArgs = list(),
  translateSql = TRUE
)

Arguments

Description

Subset cohorts using specified limit criteria. deprecated This function is deprecated. Please use 'createDemographicSubsetOperator()' instead.

Usage

createDemographicSubset(...)

Arguments

Description

Create createDemographicSubset Subset operator

Usage

createDemographicSubsetOperator(
  name = NULL,
  ageMin = 0,
  ageMax = 99999,
  gender = NULL,
  race = NULL,
  ethnicity = NULL
)

Arguments

See Also

Other subsets: createCohortSubsetOperator(), createLimitSubsetOperator()

Description

This function creates an empty cohort set data.frame for use with generateCohortSet.

Usage

createEmptyCohortDefinitionSet(verbose = FALSE)

Arguments

Value

Invisibly returns an empty cohort set data.frame

Description

This function creates an empty cohort set data.frame for use with generateNegativeControlOutcomeCohorts.

Usage

createEmptyNegativeControlOutcomeCohortSet(verbose = FALSE)

Arguments

Value

Invisibly returns an empty negative control outcome cohort set data.frame

Description

Subset cohorts using specified limit criteria. deprecated This function is deprecated. Please use 'createLimitSubsetOperator()' instead.

Usage

createLimitSubset(...)

Arguments

Description

Subset cohorts using specified limit criteria

Usage

createLimitSubsetOperator(
  name = NULL,
  priorTime = 0,
  followUpTime = 0,
  minimumCohortDuration = 0,
  maximumCohortDuration = NULL,
  limitTo = "all",
  calendarStartDate = NULL,
  calendarEndDate = NULL
)

Arguments

See Also

Other subsets: createCohortSubsetOperator(), createDemographicSubsetOperator()

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.

Description

Template cohort definition for all RxNorm ingredients. This cohort will use the vocabulary tables to automatically generate a set of cohorts that have the cohortId = conceptId * 1000. The "identifierExpression" can be customized for uniqueness.

Usage

createRxNormCohortTemplateDefinition(
  connection,
  identifierExpression = "CAST(concept_id as bigint) * 1000",
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cohortDatabaseSchema,
  priorObservationPeriod = 365,
  nameSuffix = "",
  vocabularyDatabaseSchema = cdmDatabaseSchema
)

Arguments

Value

A CohortTemplateDefinition instance

Description

Template cohort definition for all OHDSI standard conditions. The cohortId = conceptId * 1000. The "identifierExpression" can be customized for uniqueness. This definition uses any valid SNOMED condition code and all its descendants.

Excluded terms include word patterns:

' '

Cohorts are first event.

Usage

createSnomedCohortTemplateDefinition(
  connection,
  identifierExpression = "CAST(concept_id as bigint) * 1000",
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  priorObservationPeriod = 365,
  requireSecondDiagnosis = FALSE,
  nameSuffix = "",
  vocabularyDatabaseSchema = cdmDatabaseSchema
)

Arguments

Value

A CohortTemplateDefinition instance

Description

This function is used to create a relative time window for cohort subset operations. The cohort window allows you to define an interval of time relative to the target cohort's start/end date and the subset cohort's start/end date.

Usage

createSubsetCohortWindow(
  startDay,
  endDay,
  targetAnchor,
  subsetAnchor = NULL,
  negate = FALSE
)

Arguments

Value

a SubsetCohortWindow instance

Description

This is a union between all cohorts within a specified set of ids. If an individual has multiple overlapping eras, they will be merged into a single time window.

Distinct eras will be mapped to the same cohort id but remain distinct. For example:

“' A: [——–] B: [–] C: [——-] “' Becomes: “' A U B U C: [————–] “'

And “' A: [——–] B: [——-] “' Becomes “' A U B: [——–] [——-] “' It is never allowed to have multiple overlapping eras for the same individual within a cohort

Usage

createUnionCohortTemplate(cohortIds, cohortName, unionCohortId)

Arguments

Description

Operators for subsetting a cohort by demographic criteria

Value

char vector Get auto generated name

Super class

CohortGenerator::SubsetOperator -> DemographicSubsetOperator

Active bindings

Methods

Public methods

• DemographicSubsetOperator$toList()

• DemographicSubsetOperator$mapGenderConceptsToNames()

• DemographicSubsetOperator$getAutoGeneratedName()

• DemographicSubsetOperator$toJSON()

• DemographicSubsetOperator$isEqualTo()

• DemographicSubsetOperator$getGender()

• DemographicSubsetOperator$getRace()

• DemographicSubsetOperator$getEthnicity()

• DemographicSubsetOperator$clone()

Method toList()

List representation of object Map gender concepts to names

Usage

DemographicSubsetOperator$toList()

Method mapGenderConceptsToNames()

Usage

DemographicSubsetOperator$mapGenderConceptsToNames(
  mapping = list(`8507` = "males", `8532` = "females", `0` = "unknown gender")
)

Arguments

Method getAutoGeneratedName()

name generated from subset operation properties

Usage

DemographicSubsetOperator$getAutoGeneratedName()

Returns

character

Method toJSON()

json serialized representation of object

Usage

DemographicSubsetOperator$toJSON()

Method isEqualTo()

Compare Subset to another

Usage

DemographicSubsetOperator$isEqualTo(criteria)

Arguments

Method getGender()

Gender getter - used when constructing SQL to default NULL to an empty string

Usage

DemographicSubsetOperator$getGender()

Method getRace()

Race getter - used when constructing SQL to default NULL to an empty string

Usage

DemographicSubsetOperator$getRace()

Method getEthnicity()

Ethnicity getter - used when constructing SQL to default NULL to an empty string

Usage

DemographicSubsetOperator$getEthnicity()

Method clone()

The objects of this class are cloneable with this method.

Usage

DemographicSubsetOperator$clone(deep = FALSE)

Arguments

Description

This function drops the cohort statistics tables.

Usage

dropCohortStatsTables(
  connectionDetails = NULL,
  connection = NULL,
  cohortDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  dropCohortTable = FALSE
)

Arguments

Description

This function retrieves the data from the cohort statistics tables and writes them to the inclusion statistics folder specified in the function call. NOTE: inclusion rule names are handled in one of two ways:

1. You can specify the cohortDefinitionSet parameter and the inclusion rule names will be extracted from the data.frame. 2. You can insert the inclusion rule names into the database using the insertInclusionRuleNames function of this package.

The first approach is preferred as to avoid the warning emitted.

Usage

exportCohortStatsTables(
  connectionDetails,
  connection = NULL,
  cohortDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  cohortStatisticsFolder,
  snakeCaseToCamelCase = TRUE,
  fileNamesInSnakeCase = FALSE,
  incremental = FALSE,
  databaseId = NULL,
  minCellCount = 5,
  cohortDefinitionSet = NULL,
  tablePrefix = ""
)

Arguments

Description

This function retrieves the data from the cohort subset statistics table and writes them to the subset statistics folder specified in the function call.

Usage

exportCohortSubsetStatsTables(
  connectionDetails,
  connection = NULL,
  cohortDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  cohortSubsetStatisticsFolder,
  snakeCaseToCamelCase = TRUE,
  fileNamesInSnakeCase = FALSE,
  databaseId = NULL,
  minCellCount = 5,
  tablePrefix = ""
)

Arguments

Description

This function generates a set of cohorts in the cohort table.

Usage

generateCohortSet(
  connectionDetails = NULL,
  connection = NULL,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cohortDatabaseSchema = cdmDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  cohortDefinitionSet = NULL,
  stopOnError = TRUE,
  incremental = FALSE,
  incrementalFolder = NULL
)

Arguments

Value

A data.frame consisting of the following columns:

cohortId

The unique integer identifier of the cohort

cohortName

The cohort's name

generationStatus

The status of the generation task which may be one of the following:

COMPLETE

The generation completed successfully

FAILED

The generation failed (see logs for details)

SKIPPED

If using incremental == 'TRUE', this status indicates that the cohort's generation was skipped since it was previously completed.

startTime

The start time of the cohort generation. If the generationStatus == 'SKIPPED', the startTime will be NA.

endTime

The end time of the cohort generation. If the generationStatus == 'FAILED', the endTime will be the time of the failure. If the generationStatus == 'SKIPPED', endTime will be NA.

Description

This function generate a set of negative control outcome cohorts. For more information please see [Chapter 12 - Population Level Estimation](https://ohdsi.github.io/TheBookOfOhdsi/PopulationLevelEstimation.html) for more information how these cohorts are utilized in a study design.

Usage

generateNegativeControlOutcomeCohorts(
  connectionDetails = NULL,
  connection = NULL,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cohortDatabaseSchema = cdmDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  cohortTable = cohortTableNames$cohortTable,
  negativeControlOutcomeCohortSet,
  occurrenceType = "all",
  incremental = FALSE,
  incrementalFolder = NULL,
  detectOnDescendants = FALSE
)

Arguments

Value

Invisibly returns an empty negative control outcome cohort set data.frame

Description

Computes the subject and entry count per cohort. Note the cohortDefinitionSet parameter is optional - if you specify the cohortDefinitionSet, the cohort counts will be joined to the cohortDefinitionSet to include attributes like the cohortName.

Usage

getCohortCounts(
  connectionDetails = NULL,
  connection = NULL,
  cohortDatabaseSchema,
  cohortTable = "cohort",
  cohortIds = c(),
  cohortDefinitionSet = NULL,
  databaseId = NULL
)

Arguments

Value

A data frame with cohort counts

Description

This function supports the legacy way of retrieving a cohort definition set from the file system or in a package. This function supports the legacy way of storing a cohort definition set in a package with a CSV file, JSON files, and SQL files in the 'inst' folder.

Usage

getCohortDefinitionSet(
  settingsFileName = "Cohorts.csv",
  jsonFolder = "cohorts",
  sqlFolder = "sql/sql_server",
  cohortFileNameFormat = "%s",
  cohortFileNameValue = c("cohortId"),
  subsetJsonFolder = "inst/cohort_subset_definitions/",
  templateFolder = "inst/cohort_template_definitions/",
  packageName = NULL,
  warnOnMissingJson = TRUE,
  verbose = FALSE
)

Arguments

Value

Returns a cohort set data.frame

Description

This function returns a data frame of the inclusion rules defined in a cohort definition set.

Usage

getCohortInclusionRules(cohortDefinitionSet)

Arguments

Description

This function returns a data frame of the data in the Cohort Inclusion Tables. Results are organized in to a list with 6 different data frames:

• cohortInclusionTable

• cohortInclusionResultTable

• cohortInclusionStatsTable

• cohortSummaryStatsTable

• cohortCensorStatsTable

• cohortAttritionTable

These can be optionally specified with the outputTables. See exportCohortStatsTables function for saving data to csv.

Usage

getCohortStats(
  connectionDetails,
  connection = NULL,
  cohortDatabaseSchema,
  databaseId = NULL,
  snakeCaseToCamelCase = TRUE,
  outputTables = c("cohortInclusionTable", "cohortInclusionResultTable",
    "cohortInclusionStatsTable", "cohortInclusionStatsTable", "cohortSummaryStatsTable",
    "cohortCensorStatsTable", "cohortAttritionTable"),
  cohortTableNames = getCohortTableNames(),
  inclusionRules = NULL
)

Arguments

Description

This function creates a list of table names used by createCohortTables to specify the table names to create. Use this function to specify the names of the main cohort table and cohort statistics tables.

Usage

getCohortTableNames(
  cohortTable = "cohort",
  cohortSampleTable = cohortTable,
  cohortInclusionTable = paste0(cohortTable, "_inclusion"),
  cohortInclusionResultTable = paste0(cohortTable, "_inclusion_result"),
  cohortInclusionStatsTable = paste0(cohortTable, "_inclusion_stats"),
  cohortSummaryStatsTable = paste0(cohortTable, "_summary_stats"),
  cohortCensorStatsTable = paste0(cohortTable, "_censor_stats"),
  cohortSubsetAttritionTable = paste0(cohortTable, "_subset_attrition"),
  cohortChecksumTable = paste0(cohortTable, "_checksum")
)

Arguments

Value

A list of the table names as specified in the parameters to this function.

Description

Using custom sql, it is possible to generate cohorts that are not technically definitions. Invalid cohorts include the following:

* Cohorts where individuals have multiple, overlapping eras * Cohorts that have start dates that occur after their end dates * Cohorts with duplicate entries for the same subject.

Additionally the count for cohorts that lie outside the observation period for individuals is added. However, due to valid reasons in cohort definitions (e.g. fixed cohort duration, data source context) this cannot be directly considered a pass/fail diagnostic in all contexts.

Note - this code cannot formally verify the validity of a cohort. There may be situations where the logic of a cohort definition only causes errors in certain circumstances. Furthermore, if cohort counts are 0 this check is unable to evaluate validity at all.

The returned data.frame counts the number of errors found for each cohort. In addition a boolean "valid" field is applied that is TRUE only in the case where all counts are 0.

Usage

getCohortValidationCounts(
  connectionDetails = NULL,
  connection = NULL,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cohortDatabaseSchema = cdmDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  cohortIds = NULL
)

Arguments

Value

a data.frame with the fields cohortId, overlappingErasCount, invalidDateCount, duplicateCount, outsideObservationCount

Description

Returns ResultModelManager DataMigrationManager instance.

Usage

getDataMigrator(connectionDetails, databaseSchema, tablePrefix = "")

Arguments

Value

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

Description

Get the exclusion on index subset definition ids from a cohort definition set (if any have been added) Useful if keeping track in a script with complex business logic around what a cohort definition is for

Usage

getExcludeOnIndexSubsetDefinitionIds(cohortDefinitionSet)

Arguments

Description

Get the indication subset definition ids from a cohort definition set (if any have been added) Useful if keeping track in a script with complex business logic around what a cohort definition is for

Usage

getIndicationSubsetDefinitionIds(cohortDefinitionSet)

Arguments

Description

This gets a log of the last checksum for each cohort id stored in the cohort_checksum table.

This should be used to audit cohort generation as (if generated with cohort_generator) cohorts should always have an end time in this table. The last end time will be the cohort that is in the cohort table (assuming no other manual modifications are made to the cohort table itself).

This can be used downstream of CohortGenerator to evaluate if cohorts are consistent with passed definitions.

Usage

getLastGeneratedCohortChecksums(
  connectionDetails = NULL,
  connection = NULL,
  cohortId = NULL,
  cohortDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  .checkTables = TRUE
)

Arguments

Description

Get the restriction subset definition ids from a cohort definition set (if any have been added) Useful if keeping track in a script with complex business logic around what a cohort definition is for

Usage

getRestrictionSubsetDefinitionIds(cohortDefinitionSet)

Arguments

Description

Get specifications for CohortGenerator results data model

Usage

getResultsDataModelSpecifications()

Value

A tibble data frame object with specifications

Description

Get the subset definitions (if any) applied to a cohort definition set. Note that these subset definitions are a copy of those applied to the cohort set. Modifying these definitions will not modify the base cohort set. To apply a modification, reapply the subset definition to the cohort definition set data.frame with addCohortSubsetDefinition with 'overwriteExisting = TRUE'.

Usage

getSubsetDefinitions(cohortDefinitionSet)

Arguments

Value

list of cohort subset definitions or empty list

Description

Extract template definitions from a cohort definition set

Usage

getTemplateDefinitions(cohortDefinitionSet)

Arguments

Description

This function will take a cohortDefinitionSet that inclusions the Circe JSON representation of each cohort, parse the InclusionRule property to obtain the inclusion rule name and sequence number and insert the values into the cohortInclusionTable. This function is only required when generating cohorts that include cohort statistics.

Usage

insertInclusionRuleNames(
  connectionDetails = NULL,
  connection = NULL,
  cohortDefinitionSet,
  cohortDatabaseSchema,
  cohortInclusionTable = getCohortTableNames()$cohortInclusionTable
)

Arguments

Value

A data frame containing the inclusion rules by cohort and sequence ID

Description

This function is used check if a string conforms to the lower camel case format.

Usage

isCamelCase(x)

Arguments

Value

TRUE if the string is in lower camel case

Description

This function checks a data.frame to verify it holds the expected format for a cohortDefinitionSet.

Usage

isCohortDefinitionSet(x)

Arguments

Value

Returns TRUE if the input is a cohortDefinitionSet or returns FALSE with warnings on any violations

Description

This function is used to check a data.frame to ensure all column names are in snake case format.

Usage

isFormattedForDatabaseUpload(x, warn = TRUE)

Arguments

Value

Returns TRUE if all columns are snake case format. If warn == TRUE, the function will emit a warning on the column names that are not in snake case format.

Description

This function is used check if a string conforms to the snake case format.

Usage

isSnakeCase(x)

Arguments

Value

TRUE if the string is in snake case

Description

operator to apply limiting subset operations (e.g. washout periods, calendar ranges or earliest entries)

Get auto generated name

Super class

CohortGenerator::SubsetOperator -> LimitSubsetOperator

Active bindings

Methods

Public methods

• LimitSubsetOperator$getAutoGeneratedName()

• LimitSubsetOperator$toList()

• LimitSubsetOperator$clone()

Method getAutoGeneratedName()

name generated from subset operation properties

Usage

LimitSubsetOperator$getAutoGeneratedName()

Returns

character To List

Method toList()

List representation of object

Usage

LimitSubsetOperator$toList()

Method clone()

The objects of this class are cloneable with this method.

Usage

LimitSubsetOperator$clone(deep = FALSE)

Arguments

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 PostgreSQL backend) or have kept the csv/zip files from your data generation.

Usage

migrateDataModel(connectionDetails, databaseSchema, tablePrefix = "")

Arguments

Description

A data set containing sample drug exposures for 2 drugs

Usage

omopCdmDrugExposure

Format

A data frame with 8 rows and 5 variables:

drug_exposure_id

A unique identifier for the drug exposure

person_id

An integer representing the patient

drug_concept_id

An integer concept ID representing the drug concept

drug_exposure_start_date

Drug start date

drug_exposure_end_date

Drug end date

Source

Fictional data for demonstration.

Description

A data set containing sample persons

Usage

omopCdmPerson

Format

A data frame with 12 rows and 5 variables:

person_id

A unique identifier for the person

gender_concept_id

An integer concept ID representing the person's gender

year_of_birth

Year of birth

race_concept_id

An integer concept ID representing the person's race

ethnicity_concept_id

An integer concept ID representing the person's ethnicity

Source

Fictional data for demonstration.

Description

This function is used to centralize the function for reading .csv files across the HADES ecosystem. This function will automatically convert from snake_case in the file to camelCase in the data.frame returned as is the standard described in: https://ohdsi.github.io/Hades/codeStyle.html#Interfacing_between_R_and_SQL

Usage

readCsv(file, warnOnCaseMismatch = TRUE, colTypes = readr::cols())

Arguments

Value

A tibble with the .csv contents

Description

Run a cohort generation and export results

Usage

runCohortGeneration(
  connectionDetails,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cohortDatabaseSchema = cdmDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  cohortDefinitionSet = NULL,
  negativeControlOutcomeCohortSet = NULL,
  occurrenceType = "all",
  detectOnDescendants = FALSE,
  stopOnError = TRUE,
  outputFolder,
  databaseId = 1,
  minCellCount = 5,
  incremental = FALSE,
  incrementalFolder = NULL
)

Arguments

Details

Run a cohort generation for a set of cohorts and negative control outcomes. This function will also export the results of the run to the 'outputFolder'.

Description

Create 1 or more sample of size n of a cohort definition set

Subsetted cohorts can be sampled, as with any other subset form. However, subsetting a sampled cohort is not recommended and not currently supported at this time. In the case where n > cohort count the entire cohort is copied unmodified

As different databases have different forms of randomness, the random selection is computed in R, based on the count for each cohort. This is, therefore, db platform independent

Note, this function assumes cohorts have already been generated.

Lifecycle Note: This functionality is considered experimental and not intended for use inside analytic packages

Usage

sampleCohortDefinitionSet(
  cohortDefinitionSet,
  cohortIds = cohortDefinitionSet$cohortId,
  connectionDetails = NULL,
  connection = NULL,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cohortDatabaseSchema,
  outputDatabaseSchema = cohortDatabaseSchema,
  cohortTableNames = getCohortTableNames(),
  n = NULL,
  sampleFraction = NULL,
  seed = 64374,
  seedArgs = NULL,
  identifierExpression = "cohortId * 1000 + seed",
  incremental = FALSE,
  incrementalFolder = NULL
)

Arguments

Value

sampledCohortDefinitionSet - a data.frame like object that contains the resulting identifiers and modified names of cohorts

Description

This function saves a cohortDefinitionSet to the file system and provides options for specifying where to write the individual elements: the settings file will contain the cohort information as a CSV specified by the settingsFileName, the cohort JSON is written to the jsonFolder and the SQL is written to the sqlFolder. We also provide a way to specify the json/sql file name format using the cohortFileNameFormat and cohortFileNameValue parameters.

Usage

saveCohortDefinitionSet(
  cohortDefinitionSet,
  settingsFileName = "inst/Cohorts.csv",
  jsonFolder = "inst/cohorts",
  sqlFolder = "inst/sql/sql_server",
  cohortFileNameFormat = "%s",
  cohortFileNameValue = c("cohortId"),
  subsetJsonFolder = "inst/cohort_subset_definitions/",
  templateFolder = "inst/cohort_template_definitions/",
  verbose = FALSE
)

Arguments

Description

This is generally used as part of saveCohortDefinitionSet

Usage

saveCohortSubsetDefinition(
  subsetDefinition,
  subsetJsonFolder = "inst/cohort_subset_definitions/"
)

Arguments

Description

Representation of a time window to use when subsetting a target cohort with a subset cohort

Active bindings

Methods

Public methods

• SubsetCohortWindow$toList()

• SubsetCohortWindow$toJSON()

• SubsetCohortWindow$isEqualTo()

• SubsetCohortWindow$clone()

Method toList()

List representation of object To JSON

Usage

SubsetCohortWindow$toList()

Method toJSON()

json serialized representation of object Is Equal to

Usage

SubsetCohortWindow$toJSON()

Method isEqualTo()

Compare SubsetCohortWindow to another

Usage

SubsetCohortWindow$isEqualTo(criteria)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

SubsetCohortWindow$clone(deep = FALSE)

Arguments

Description

Abstract Base Class for subsets. Subsets should inherit from this and implement their own requirements.

Active bindings

Methods

Public methods

• SubsetOperator$new()

• SubsetOperator$classname()

• SubsetOperator$getAutoGeneratedName()

• SubsetOperator$getQueryBuilder()

• SubsetOperator$publicFields()

• SubsetOperator$isEqualTo()

• SubsetOperator$toList()

• SubsetOperator$toJSON()

• SubsetOperator$print()

• SubsetOperator$clone()

Method new()

Usage

SubsetOperator$new(definition = NULL)

Arguments

Returns

instance of object Class Name

Method classname()

Class name of object Get auto generated name

Usage

SubsetOperator$classname()

Method getAutoGeneratedName()

Not intended to be used - should be implemented in subclasses Return query builder instance

Usage

SubsetOperator$getAutoGeneratedName()

Method getQueryBuilder()

Return query builder instance Public Fields

Usage

SubsetOperator$getQueryBuilder(id)

Arguments

Method publicFields()

Publicly settable fields of object Is Equal to

Usage

SubsetOperator$publicFields()

Method isEqualTo()

Compare Subsets - are they identical or not? Checks all fields and settings

Usage

SubsetOperator$isEqualTo(subsetOperatorB)

Arguments

Method toList()

convert to List representation To Json

Usage

SubsetOperator$toList()

Method toJSON()

convert to json serialized representation

Usage

SubsetOperator$toJSON()

Returns

list representation of object as json character Pretty print

Method print()

Usage

SubsetOperator$print(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

SubsetOperator$clone(deep = FALSE)

Arguments

See Also

CohortSubsetOperator

DemographicSubsetOperator

LimitSubsetOperator

Description

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

Usage

uploadResults(
  connectionDetails,
  schema,
  resultsFolder,
  forceOverWriteOfSpecifications = FALSE,
  purgeSiteDataBeforeUploading = TRUE,
  tablePrefix = "",
  ...
)

Arguments

Description

This function is used to centralize the function for writing .csv files across the HADES ecosystem. This function will automatically convert from camelCase in the data.frame to snake_case column names in the resulting .csv file as is the standard described in: https://ohdsi.github.io/Hades/codeStyle.html#Interfacing_between_R_and_SQL

This function may also raise warnings if the data is stored in a format that will not work with the HADES standard for uploading to a results database. Specifically file names should be in snake_case format, all column headings are in snake_case format and where possible the file name should not be plural. See isFormattedForDatabaseUpload for a helper function to check a data.frame for rules on the column names

Usage

writeCsv(
  x,
  file,
  append = FALSE,
  warnOnCaseMismatch = TRUE,
  warnOnFileNameCaseMismatch = TRUE,
  warnOnUploadRuleViolations = TRUE
)

Arguments

Value

Returns the input x invisibly.