R/CreateArgFunctions.R

In escott12/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 excludeDrugsFromCovariates   DEPRECATED: Should the target and comparator drugs (and their
#'                                     descendant concepts) be excluded from the covariates? Note that
#'                                     this will work if the drugs are actually drug concept IDs (and
#'                                     not cohort IDs).
#' @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 = "",
                                            excludeDrugsFromCovariates = NULL,
                                            firstExposureOnly = FALSE,
                                            removeDuplicateSubjects = FALSE,
                                            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 addExposureDaysToStart           DEPRECATED: Add the length of exposure the start of the risk
#'                                         window? Use startAnchor instead.
#' @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 addExposureDaysToEnd             DEPRECATED: Add the length of exposure the risk window? Use
#'                                         endAnchor instead.
#' @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 = FALSE,
                                            removeSubjectsWithPriorOutcome = TRUE,
                                            priorOutcomeLookback = 99999,
                                            minDaysAtRisk = 1,
                                            maxDaysAtRisk = 99999,
                                            riskWindowStart = 0,
                                            addExposureDaysToStart = NULL,
                                            startAnchor = "cohort start",
                                            riskWindowEnd = 0,
                                            addExposureDaysToEnd = NULL,
                                            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.
#'
#' @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,
                                                       tolerance = 2e-07,
                                                       cvRepetitions = 10,
                                                       startingVariance = 0.01)) {
  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.
#' @param estimator   The type of estimator. Options are estimator = "ate" for the average treatment
#'                    effect, and estimator = "att"for the average treatment effect in the treated.
#'
#' @export
createTrimByIptwArgs <- function(maxWeight = 10, estimator = "ate") {
  analysis <- list()
  for (name in names(formals(createTrimByIptwArgs))) {
    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 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)? See details.
#' @param estimator                 for IPTW: the type of estimator. Options are estimator = "ate" for
#'                                  the average treatment effect, and estimator = "att"for the average
#'                                  treatment effect in the treated.
#' @param maxWeight                 for IPTW: the maximum weight. Larger values will be truncated to
#'                                  this value. maxWeight = 0 means no truncation takes place.
#' @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,
                                      estimator = "ate",
                                      maxWeight = 0,
                                      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,
                                                              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)
}