Executes IR analysis given a design, options, and connection settings.
Source:R/CohortIncidence.R
executeAnalysis.RdExecutes IR analysis given a design, options, and connection settings.
Usage
executeAnalysis(
connectionDetails = NULL,
connection = NULL,
incidenceDesign,
buildOptions,
sourceName = "default"
)Arguments
- connectionDetails
An R object of type
connectionDetailscreated using the functioncreateConnectionDetailsin theDatabaseConnectorpackage. Either theconnectionorconnectionDetailsargument should be specified.- connection
A connection to the server containing the schema as created using the
connectfunction in theDatabaseConnectorpackage. Either theconnectionorconnectionDetailsargument should be specified.- incidenceDesign
A string object containing valid JSON that represents cohort incidence design
- buildOptions
the parameters to use in building the analysis queries, created by buildOptions()
- sourceName
the source name to attach to the results
Value
A named list of data.frame objects containing the IR results. The list includes incidence_summary, target_def, outcome_def, tar_def, age_group_def, and subgroup_def, each representing one result table produced during execution.
Details
This method performs the entire cohort incidence analysis in one step without the need for creating any permenant tables.
The process for calculating the cohort incidence is as follows:
Create the time at risk episodes from the target cohorts, using the specified startWith, endWith and offsets
Calculate the excluded time by finding the overlap of TAR with the following:
Outcome cohort episodes (adding the clean window to each outcome episode end date)
Exclusion cohort that was specified in the outcome definition excludeCohortId.
Count the distinct persons, distinct persons with cases, total time at risk and total cases, and calcuate the proportion and rates.
The resut contains the following dataframes:
incidence_summary:
| Name | Description |
| REF_ID | The reference id specified in buildOptions() to track results to the analysis execution. |
| SOURCE_NAME | The name of the source for these results |
| TARGET_COHORT_DEFIITION_ID | The cohort ID of the target population |
| TAR_ID | The TAR identifier |
| SUBGROUP_ID | The subgroup identifier |
| OUTCOME_ID | The outcome identifier |
| AGE_GROUP_ID | The age ID for this strata representing the age band specified in the strata settings |
| GENDER_ID | The gender concept ID for this gender strata |
| GENDER_NAME | The name of the gender |
| START_YEAR | The year strata, defined by using the year the TAR started |
| PERSONS_AT_RISK_PE | Distinct persons at risk before removing excluded time from TAR |
| PERSONS_AT_RISK | Distinct persons at risk after removing excluded time from TAR. A person must have at least 1 day TAR to be included. |
| PERSON_DAYS_PE | Total TAR (in days) before excluded time was removed from TAR. |
| PERSON_DAYS | Total TAR (in days) after excluded time was removed from TAR. |
| PERSON_OUTCOMES_PE | Distinct persons with outcome before removing excluded time from TAR |
| PERSON_OUTCOMES | Distinct persons with outcome after removing excluded time from TAR. A person must have at least 1 day TAR to be included. |
| OUTCOMES_PE | Number of cases before excluding TAR. |
| OUTCOMES | Number of cases after excluding TAR. |
| INCIDENCE_PROPORTION_P100P | The Incidence Proportion (per 100 people), calculated by person_outcomes / persons_at_risk * 100 |
| INCIDENCE_RATE_P100PY | The Incidence Rate (per 100 person years), calculated by outcomes / person_days / 365.25 * 100 |
| target_def: | |
| Name | Description |
| —– | ——– |
| REF_ID | The reference id specified in buildOptions() to track results to the analysis execution. |
| TARGET_COHORT_DEFIITION_ID | The cohort ID of the target population |
| TARGET_NAME | The name of the target cohort |
outcome_def:
| Name | Description |
| REF_ID | The reference id specified in buildOptions() to track results to the analysis execution. |
| OUTCOME_ID | The outcome identifier |
| OUTCOME_COHORT_DEFINITION_ID | The cohort ID of the outcome population |
| OUTCOME_NAME | The outcome name |
| CLEAN_WINDOW | The clean window for this outcome definition |
| EXCLUDED_COHORT_DEFINITION_ID | The cohort used to exclude TAR |
tar_def:
| Name | Description |
| REF_ID | The reference id specified in buildOptions() to track results to the analysis execution. |
| TAR_ID | The TAR identifier |
| TAR_START_WITH | Indicates if the TAR starts with the 'start' or 'end' of the target cohort episode |
| TAR_START_OFFSET | The days added to the date field specified in TAR_START_WITH |
| TAR_END_WITH | Indicates if the TAR ends with the 'start' or 'end' of the target cohort episode |
| TAR_END_OFFSET | The days added to the date field specified in TAR_END_WITH |
age_group_def:
| Name | Description |
| REF_ID | The reference id specified in buildOptions() to track results to the analysis execution. |
| AGE_GROUP_ID | The age ID for this strata representing the age band specified in the strata settings |
| AGE_GROUP_NAME | The name for this age group |
| MIN_AGE | The minimum age for this group |
| MAX_AGE | the max age for this group |
subgroup_def:
| Name | Description |
| REF_ID | The reference id specified in buildOptions() to track results to the analysis execution. |
| SUBGROUP_NAME | The name of the subgroup |