LocalControl: Local Control

Description Usage Arguments Value References Examples

View source: R/localControl.R

Description

Implements a non-parametric methodology for correcting biases when comparing the outcomes of two treatments in a cross-sectional or case control observational study. This implementation of Local Control uses nearest neighbors to each point within a given radius to compare treatment outcomes. Local Control matches along a continuum of similarity (radii), clustering the near neighbors to a given observation by variables thought to be sources of bias and confounding. This is analogous to combining a host of smaller studies that are each homogeneous within themselves, but represent the spectrum of variability of observations across diverse subpopulations. As the clusters get smaller, some of them can become noninformative, whereby all cluster members contain only one treatment, and there is no basis for comparison. Each observation has a unique set of near-neighbors, and the approach becomes more akin to a non-parametric density estimate using similar observations within a covariate hypersphere of a given radius. The global treatment difference is taken as the average of the treatment differences of the neighborhood around each observation.

While LocalControlClassic uses the number of clusters as a varying parameter to visualize treatment differences as a function of similarity of observations, this function instead uses a varying radius. The maximum radius enclosing all observations corresponds to the biased estimate which compares the outcome of all those with treatment A versus all those with treatment B. An easily interpretable graph can be created to illustrate the change in estimated outcome difference between two treatments, on average, across all clusters, as a function of using smaller and more homogenous clusters. The LocalControlNearestNeighborsConfidence procedure statistically resamples this Local Control process to generate confidence estimates. It is also helpful to plot a box-plot of the local treatment difference at a radius of zero, requiring that every observation has at least one perfect match on the other treatment. When perfect matches exist, one can estimate the treatment difference without making assumptions about the relative importance of the clustering variables. The plot.LocalControlCS function will plot both visualizations in a single graph.

Usage

1
2
3
4
5
LocalControl(data, modelForm = NULL, outcomeType = "cross-sectional",
  treatmentColName, outcomeColName, cenCode = 0, clusterVars,
  timeColName = "", treatmentCode, labelColName = "", radStepType = "exp",
  radDecayRate = 0.8, radMinFract = 0.01, radiusLevels = numeric(),
  normalize = TRUE, verbose = FALSE, numThreads = 1)

Arguments

data

DataFrame containing all variables which will be used for the analysis.

modelForm

A formula containing the necessary variables for Local Control analysis. This can be used as an alternative to the primary interface for cross-sectional studies. The formula should be in the following format: "outcome ~ treatment | clusterVar1 ... clusterVarN".

outcomeType

Specifys the outcome type for the analysis. Defaults to cross-sectional.

treatmentColName

A string containing the name of a column in data. The column contains the treatment variable specifying the treatment groups.

outcomeColName

A string containing the name of a column in data. The column contains the outcome variable to be compared between the treatment groups.

cenCode

A value specifying which of the outcome values corresponds to a censored observation.

clusterVars

A character vector containing column names in data. Each column contains an X-variable, or covariate which will be used to form patient clusters.

timeColName

A string containing the name of a column in data. The column contains the time to outcome for each of the observations in data.

treatmentCode

(optional) A string containing one of the factor levels from the treatment column. If provided, the corresponding treatment will be considered "Treatment 1". Otherwise, the first "level" of the column will be considered the primary treatment.

labelColName

(optional) A string containing the name of a column from data. The column contains labels for each of the observations in data, defaults to the row indices.

radStepType

(optional) Used in the generation of correction radii. The step type used to generate each correction radius after the maximum. Currently accepts "unif" and "exp" (default). "unif" for uniform decay ex: (radDecayRate = 0.1) (1, 0.9, 0.8, 0.7, ..., ~minRadFract, 0) "exp" for exponential decay ex: (radDecayRate = 0.9) (1, 0.9, 0.81, 0.729, ..., ~minRadFract, 0)

radDecayRate

(optional) Used in the generation of correction radii. The size of the "step" between each of the generated correction radii. If radStepType == "exp", radDecayRate must be a value between (0,1). This value defaults to 0.8.

radMinFract

(optional) Used in the generation of correction radii. A floating point number representing the smallest fraction of the maximum radius to use as a correction radius.

radiusLevels

(optional) By default, Local Control builds a set of radii to fit data. The radiusLevels parameter allows users to override the construction by explicitly providing a set of radii.

normalize

(optional) Logical value. Tells local control if it should or should not normalize the covariates. Default is TRUE.

verbose

(optional) Logical value. Display or suppress the console output during the call to Local Control. Default is FALSE.

numThreads

(optional) An integer value specifying the number of threads which will be assigned to the analysis. The maximum number of threads varies depending on the system hardware. Defaults to 1 thread.

Value

A list containing the results from the call to LocalControl.

References

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 # cross-sectional

 data(lindner)
 linVars <- c("stent", "height", "female", "diabetic", "acutemi",
              "ejecfrac", "ves1proc")
 csresults = LocalControl(data = lindner,
                          clusterVars = linVars,
                          treatmentColName = "abcix",
                          outcomeColName = "cardbill",
                          treatmentCode = 1)
 plot(csresults)


 # survival / competing risks example

 data(cardSim)
 crresults = LocalControl(data = cardSim, outcomeType = "survival",
                          outcomeColName = "status",
                          timeColName = "time",
                          treatmentColName = "drug",
                          treatmentCode = 1,
                          clusterVars = c("age", "bmi"))
 plot(crresults)

OHDSI/LocalControl documentation built on July 13, 2018, 3:21 p.m.