R/CreateArgFunctions.R

In OHDSI/CohortMethod: New-User Cohort Method with Large Scale Propensity and Outcome Models

# This file has been autogenerated. Do not change by hand.

#' Create a parameter object for the function getDbCohortMethodData
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param studyStartDate  A calendar date specifying the minimum date that a cohort index date can appear. Date format is 'yyyymmdd'.
#' @param studyEndDate  A calendar date specifying the maximum date that a cohort index date can appear. Date format is 'yyyymmdd'. Important: the study end data is also used to truncate risk windows, meaning no outcomes beyond the study end date will be considered.
#' @param firstExposureOnly  Should only the first exposure per subject be included? Note that this is typically done in the createStudyPopulation() function, but can already be done here for efficiency reasons.
#' @param removeDuplicateSubjects  Remove subjects that are in both the target and comparator cohort? See details for allowed values.Note that this is typically done in the createStudyPopulation function, but can already be done here for efficiency reasons.
#' @param restrictToCommonPeriod  Restrict the analysis to the period when both treatments are observed?
#' @param washoutPeriod  The minimum required continuous observation time prior to index date for a person to be included in the cohort. Note that this is typically done in the createStudyPopulation function, but can already be done here for efficiency reasons.
#' @param maxCohortSize  If either the target or the comparator cohort is larger than this number it will be sampled to this size. maxCohortSize = 0 indicates no maximum size.
#' @param covariateSettings  An object of type covariateSettings as created using the FeatureExtraction::createCovariateSettings() function.
#'
#' @export
createGetDbCohortMethodDataArgs <- function(studyStartDate = "",
                                            studyEndDate = "",
                                            firstExposureOnly = FALSE,
                                            removeDuplicateSubjects = "keep all",
                                            restrictToCommonPeriod = FALSE,
                                            washoutPeriod = 0,
                                            maxCohortSize = 0,
                                            covariateSettings) {
  analysis <- list()
  for (name in names(formals(createGetDbCohortMethodDataArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function createStudyPopulation
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param firstExposureOnly  Should only the first exposure per subject be included?
#' @param restrictToCommonPeriod  Restrict the analysis to the period when both exposures are observed?
#' @param washoutPeriod  The minimum required continuous observation time prior to index date for a person to be included in the cohort.
#' @param removeDuplicateSubjects  Remove subjects that are in both the target and comparator cohort? See details for allowed values.
#' @param removeSubjectsWithPriorOutcome  Remove subjects that have the outcome prior to the risk window start?
#' @param priorOutcomeLookback  How many days should we look back when identifying prior outcomes?
#' @param minDaysAtRisk  The minimum required number of days at risk. Risk windows with fewer days than this number are removed from the analysis.
#' @param maxDaysAtRisk  The maximum allowed number of days at risk. Risk windows that are longer will be truncated to this number of days.
#' @param riskWindowStart  The start of the risk window (in days) relative to the startAnchor.
#' @param startAnchor  The anchor point for the start of the risk window. Can be "cohort start" or "cohort end".
#' @param riskWindowEnd  The end of the risk window (in days) relative to the endAnchor.
#' @param endAnchor  The anchor point for the end of the risk window. Can be "cohort start" or "cohort end".
#' @param censorAtNewRiskWindow  If a subject is in multiple cohorts, should time-at-risk be censored when the new time-at-risk starts to prevent overlap?
#'
#' @export
createCreateStudyPopulationArgs <- function(firstExposureOnly = FALSE,
                                            restrictToCommonPeriod = FALSE,
                                            washoutPeriod = 0,
                                            removeDuplicateSubjects = "keep all",
                                            removeSubjectsWithPriorOutcome = TRUE,
                                            priorOutcomeLookback = 99999,
                                            minDaysAtRisk = 1,
                                            maxDaysAtRisk = 99999,
                                            riskWindowStart = 0,
                                            startAnchor = "cohort start",
                                            riskWindowEnd = 0,
                                            endAnchor = "cohort end",
                                            censorAtNewRiskWindow = FALSE) {
  analysis <- list()
  for (name in names(formals(createCreateStudyPopulationArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function createPs
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param excludeCovariateIds  Exclude these covariates from the propensity model.
#' @param includeCovariateIds  Include only these covariates in the propensity model.
#' @param maxCohortSizeForFitting  If the target or comparator cohort are larger than this number, they will be downsampled before fitting the propensity model. The model will be used to compute propensity scores for all subjects. The purpose of the sampling is to gain speed. Setting this number to 0 means no downsampling will be applied.
#' @param errorOnHighCorrelation  If true, the function will test each covariate for correlation with the treatment assignment. If any covariate has an unusually high correlation (either positive or negative), this will throw and error.
#' @param stopOnError  If an error occur, should the function stop? Else, the two cohorts will be assumed to be perfectly separable.
#' @param prior  The prior used to fit the model. See Cyclops::createPrior() for details.
#' @param control  The control object used to control the cross-validation used to determine the hyperparameters of the prior (if applicable). See Cyclops::createControl() for details.
#' @param estimator  The type of estimator for the IPTW. Options are estimator = "ate" for the average treatment effect, estimator = "att" for the average treatment effect in the treated, and estimator = "ato" for the average treatment effect in the overlap population.
#'
#' @export
createCreatePsArgs <- function(excludeCovariateIds = c(),
                               includeCovariateIds = c(),
                               maxCohortSizeForFitting = 250000,
                               errorOnHighCorrelation = TRUE,
                               stopOnError = TRUE,
                               prior = createPrior("laplace", exclude = c(0), useCrossValidation = TRUE),
                               control = createControl(noiseLevel = "silent", cvType = "auto", seed = 1, resetCoefficients = TRUE, tolerance = 2e-07, cvRepetitions = 10, startingVariance = 0.01),
                               estimator = "att") {
  analysis <- list()
  for (name in names(formals(createCreatePsArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function trimByPs
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param trimFraction  This fraction will be removed from each treatment group. In the target group, persons with the highest propensity scores will be removed, in the comparator group person with the lowest scores will be removed.
#'
#' @export
createTrimByPsArgs <- function(trimFraction = 0.05) {
  analysis <- list()
  for (name in names(formals(createTrimByPsArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function trimByPsToEquipoise
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param bounds  The upper and lower bound on the preference score for keeping persons.
#'
#' @export
createTrimByPsToEquipoiseArgs <- function(bounds = c(0.3, 0.7)) {
  analysis <- list()
  for (name in names(formals(createTrimByPsToEquipoiseArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function trimByIptw
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param maxWeight  The maximum allowed IPTW.
#'
#' @export
createTrimByIptwArgs <- function(maxWeight = 10) {
  analysis <- list()
  for (name in names(formals(createTrimByIptwArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function truncateIptw
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param maxWeight  The maximum allowed IPTW.
#'
#' @export
createTruncateIptwArgs <- function(maxWeight = 10) {
  analysis <- list()
  for (name in names(formals(createTruncateIptwArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function matchOnPs
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param caliper  The caliper for matching. A caliper is the distance which is acceptable for any match. Observations which are outside of the caliper are dropped. A caliper of 0 means no caliper is used.
#' @param caliperScale  The scale on which the caliper is defined. Three scales are supported: caliperScale = 'propensity score', caliperScale = 'standardized', or caliperScale = 'standardized logit'. On the standardized scale, the caliper is interpreted in standard deviations of the propensity score distribution. 'standardized logit' is similar, except that the propensity score is transformed to the logit scale because the PS is more likely to be normally distributed on that scale (Austin, 2011).
#' @param maxRatio  The maximum number of persons in the comparator arm to be matched to each person in the treatment arm. A maxRatio of 0 means no maximum: all comparators will be assigned to a target person.
#' @param allowReverseMatch  Allows n-to-1 matching if target arm is larger
#' @param stratificationColumns  Names or numbers of one or more columns in the data data.frame on which subjects should be stratified prior to matching. No persons will be matched with persons outside of the strata identified by the values in these columns.
#'
#' @export
createMatchOnPsArgs <- function(caliper = 0.2,
                                caliperScale = "standardized logit",
                                maxRatio = 1,
                                allowReverseMatch = FALSE,
                                stratificationColumns = c()) {
  analysis <- list()
  for (name in names(formals(createMatchOnPsArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function matchOnPsAndCovariates
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param caliper  The caliper for matching. A caliper is the distance which is acceptable for any match. Observations which are outside of the caliper are dropped. A caliper of 0 means no caliper is used.
#' @param caliperScale  The scale on which the caliper is defined. Three scales are supported: caliperScale = 'propensity score', caliperScale = 'standardized', or caliperScale = 'standardized logit'. On the standardized scale, the caliper is interpreted in standard deviations of the propensity score distribution. 'standardized logit' is similar, except that the propensity score is transformed to the logit scale because the PS is more likely to be normally distributed on that scale (Austin, 2011).
#' @param maxRatio  The maximum number of persons in the comparator arm to be matched to each person in the treatment arm. A maxRatio of 0 means no maximum: all comparators will be assigned to a target person.
#' @param allowReverseMatch  Allows n-to-1 matching if target arm is larger
#' @param covariateIds  One or more covariate IDs in the cohortMethodData object on which subjects should be also matched.
#'
#' @export
createMatchOnPsAndCovariatesArgs <- function(caliper = 0.2,
                                             caliperScale = "standardized logit",
                                             maxRatio = 1,
                                             allowReverseMatch = FALSE,
                                             covariateIds) {
  analysis <- list()
  for (name in names(formals(createMatchOnPsAndCovariatesArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function stratifyByPs
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param numberOfStrata  How many strata? The boundaries of the strata are automatically defined to contain equal numbers of target persons.
#' @param stratificationColumns  Names of one or more columns in the data data.frame on which subjects should also be stratified in addition to stratification on propensity score.
#' @param baseSelection  What is the base selection of subjects where the strata bounds are to be determined? Strata are defined as equally-sized strata inside this selection. Possible values are "all", "target", and "comparator".
#'
#' @export
createStratifyByPsArgs <- function(numberOfStrata = 5,
                                   stratificationColumns = c(),
                                   baseSelection = "all") {
  analysis <- list()
  for (name in names(formals(createStratifyByPsArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function stratifyByPsAndCovariates
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param numberOfStrata  Into how many strata should the propensity score be divided? The boundaries of the strata are automatically defined to contain equal numbers of target persons.
#' @param baseSelection  What is the base selection of subjects where the strata bounds are to be determined? Strata are defined as equally-sized strata inside this selection. Possible values are "all", "target", and "comparator".
#' @param covariateIds  One or more covariate IDs in the cohortMethodData object on which subjects should also be stratified.
#'
#' @export
createStratifyByPsAndCovariatesArgs <- function(numberOfStrata = 5,
                                                baseSelection = "all",
                                                covariateIds) {
  analysis <- list()
  for (name in names(formals(createStratifyByPsAndCovariatesArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function computeCovariateBalance
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param subgroupCovariateId  Optional: a covariate ID of a binary covariate that indicates a subgroup of interest. Both the before and after populations will be restricted to this subgroup before computing covariate balance.
#' @param maxCohortSize  If the target or comparator cohort are larger than this number, they will be downsampled before computing covariate balance to save time. Setting this number to 0 means no downsampling will be applied.
#' @param covariateFilter  Determines the covariates for which to compute covariate balance. Either a vector of covariate IDs, or a table 1 specifications object as generated for example using FeatureExtraction::getDefaultTable1Specifications(). If covariateFilter = NULL, balance will be computed for all variables found in the data.
#'
#' @export
createComputeCovariateBalanceArgs <- function(subgroupCovariateId = NULL,
                                              maxCohortSize = 250000,
                                              covariateFilter = NULL) {
  analysis <- list()
  for (name in names(formals(createComputeCovariateBalanceArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}

#' Create a parameter object for the function fitOutcomeModel
#'
#' @details
#' Create an object defining the parameter values.
#'
#' @param modelType  The type of outcome model that will be used. Possible values are "logistic", "poisson", or "cox".
#' @param stratified  Should the regression be conditioned on the strata defined in the population object (e.g. by matching or stratifying on propensity scores)?
#' @param useCovariates  Whether to use the covariates in the cohortMethodData object in the outcome model.
#' @param inversePtWeighting  Use inverse probability of treatment weighting (IPTW)
#' @param interactionCovariateIds  An optional vector of covariate IDs to use to estimate interactions with the main treatment effect.
#' @param excludeCovariateIds  Exclude these covariates from the outcome model.
#' @param includeCovariateIds  Include only these covariates in the outcome model.
#' @param profileGrid  A one-dimensional grid of points on the log(relative risk) scale where the likelihood for coefficient of variables is sampled. See details.
#' @param profileBounds  The bounds (on the log relative risk scale) for the adaptive sampling of the likelihood function. See details.
#' @param prior  The prior used to fit the model. See Cyclops::createPrior() for details.
#' @param control  The control object used to control the cross-validation used to determine the hyperparameters of the prior (if applicable). See Cyclops::createControl() for details.
#'
#' @export
createFitOutcomeModelArgs <- function(modelType = "logistic",
                                      stratified = FALSE,
                                      useCovariates = FALSE,
                                      inversePtWeighting = FALSE,
                                      interactionCovariateIds = c(),
                                      excludeCovariateIds = c(),
                                      includeCovariateIds = c(),
                                      profileGrid = NULL,
                                      profileBounds = c(log(0.1), log(10)),
                                      prior = createPrior("laplace", useCrossValidation = TRUE),
                                      control = createControl(cvType = "auto", seed = 1, resetCoefficients = TRUE, startingVariance = 0.01, tolerance = 2e-07, cvRepetitions = 10, noiseLevel = "quiet")) {
  analysis <- list()
  for (name in names(formals(createFitOutcomeModelArgs))) {
    analysis[[name]] <- get(name)
  }
  class(analysis) <- "args"
  return(analysis)
}