| Type: | Package |
| Title: | Generalized Power Analysis for LATE |
| Version: | 0.1.2 |
| Maintainer: | Eddie Yang <z5yang@ucsd.edu> |
| Description: | An implementation of the generalized power analysis for the local average treatment effect (LATE), proposed by Bansak (2020) <doi:10.1214/19-STS732>. Power analysis is in the context of estimating the LATE (also known as the complier average causal effect, or CACE), with calculations based on a test of the null hypothesis that the LATE equals 0 with a two-sided alternative. The method uses standardized effect sizes to place a conservative bound on the power under minimal assumptions. Package allows users to recover power, sample size requirements, or minimum detectable effect sizes. Package also allows users to work with absolute effects rather than effect sizes, to specify an additional assumption to narrow the bounds, and to incorporate covariate adjustment. |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.2.1 |
| URL: | https://github.com/kbansak/powerLATE_tutorial, https://github.com/kbansak/powerLATE |
| BugReports: | https://github.com/kbansak/powerLATE/issues |
| NeedsCompilation: | no |
| Packaged: | 2024-05-29 15:27:44 UTC; eddie |
| Author: | Kirk Bansak [aut], Eddie Yang [aut, cre] |
| Repository: | CRAN |
| Date/Publication: | 2024-05-29 19:20:02 UTC |
Subsidiary PowerLATE Function
Description
Function to load package description.
Usage
.onAttach(lib, pkg)
Arguments
lib |
libname |
pkg |
package name |
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
Subsidiary Power Calculation Function
Description
Check if input is of length greater than 1 and convert to string message if so.
Usage
checkVec(val)
Arguments
val |
parameter |
Value
Either a string message or val.
Note
This function is called internally and thus should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
Subsidiary PowerLATE Function
Description
Subsidiary function to perform power calculation under equal assignment probability and ordered mean assumption.
Usage
equal.ordered(
power = NULL,
sig.level = NULL,
pi = NULL,
kappa = NULL,
N = NULL
)
Arguments
power |
power of test (1 minus Type II error probability) |
sig.level |
significance level (Type I error probability). |
pi |
compliance rate. Equivalently, average causal effect of Z on D. |
kappa |
effect size |
N |
total number of observations |
Value
A vector of values for one in {kappa, N, power} that is not supplied by the user.
Note
This function is called internally and thus should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
See Also
equal.unordered, unequal.ordered, unequal.unordered.
Subsidiary powerLATE Function
Description
Subsidiary function to perform power calculation with covariates under equal assignment probability with ordered mean assumption.
Usage
equal.ordered.cov(
power = NULL,
sig.level = NULL,
pi = NULL,
kappa = NULL,
N = NULL,
r2dw = NULL,
r2yw = NULL
)
Arguments
power |
power of test (1 minus Type II error probability) |
sig.level |
significance level (Type I error probability). |
pi |
compliance rate. Equivalently, average causal effect of Z on D. |
kappa |
effect size |
N |
total number of observations |
r2dw |
proportion of variation in D left unexplained by Z that is explained by W. |
r2yw |
proportion of variation in Y left unexplained by Z that is explained by W. |
Value
A vector of values for one in {kappa, N, power} that is not supplied by the user.
Note
This function is called internally and thus should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
See Also
equal.unordered.cov, unequal.unordered.cov, unequal.ordered.cov.
Subsidiary PowerLATE Function
Description
Subsidiary function to perform power calculation under equal assignment probability and without ordered mean assumption.
Usage
equal.unordered(
power = NULL,
sig.level = NULL,
pi = NULL,
kappa = NULL,
N = NULL
)
Arguments
power |
power of test (1 minus Type II error probability) |
sig.level |
significance level (Type I error probability). |
pi |
compliance rate. Equivalently, average causal effect of Z on D. |
kappa |
effect size |
N |
total number of observations |
Value
A vector of values for one in {kappa, N, power} that is not supplied by the user.
Note
This function is called internally and thus should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
See Also
equal.ordered, unequal.ordered, unequal.unordered.
Subsidiary powerLATE Function
Description
Subsidiary function to perform power calculation with covariates under equal assignment probability without ordered mean assumption.
Usage
equal.unordered.cov(
power = NULL,
sig.level = NULL,
pi = NULL,
kappa = NULL,
N = NULL,
r2dw = NULL,
r2yw = NULL
)
Arguments
power |
power of test (1 minus Type II error probability) |
sig.level |
significance level (Type I error probability). |
pi |
compliance rate. Equivalently, average causal effect of Z on D. |
kappa |
effect size |
N |
total number of observations |
r2dw |
proportion of variation in D left unexplained by Z that is explained by W. |
r2yw |
proportion of variation in Y left unexplained by Z that is explained by W. |
Value
A vector of values for one in {kappa, N, power} that is not supplied by the user.
Note
This function is called internally and thus should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
See Also
equal.ordered.cov, unequal.ordered.cov, unequal.unordered.cov.
Generalized Power Analysis for LATE
Description
Function to perform generalized power analysis for the LATE (i.e. under noncompliance with treatment assignment). Function allows for user to work with either standardized effect sizes or absolute effects. The results provided presume a test of the null hypothesis that the LATE equals 0 with a two-sided alternative.
Usage
powerLATE(pZ = 0.5, pi, N, kappa,
sig.level = 0.05, power,
effect.size = TRUE, tau = NULL, omega = NULL,
assume.ord.means = FALSE, verbose = TRUE)
Arguments
pZ |
probability of being assigned to treatment. Default is 0.5, i.e. equal assignment probability. |
pi |
compliance rate. Equivalently, average causal effect of treatment assignment on treatment uptake. |
N |
total sample size. |
kappa |
LATE effect size (i.e. effect size for compliers). |
sig.level |
significance level (Type I error probability). Default is 0.05. |
power |
power of test (1 minus Type II error probability). |
effect.size |
whether effect size (kappa) rather than absolute effect (tau) is used in power calculations. Default is |
tau |
LATE absolute effect (i.e. absolute effect for compliers). Must only be supplied if |
omega |
within-group standard deviation of the outcome. Must be supplied if |
assume.ord.means |
whether ordered means assumption is made. Default is |
verbose |
print input and output parameter values. Default is |
Details
If effect.size = TRUE (the default setting), exactly two of the parameters {kappa, N, power} must be supplied,
from which the third (target) parameter will be calculated. If effect.size = FALSE, omega must be supplied, and exactly two of
the parameters {tau, N, power} must be supplied. pi must always be supplied, and the user can change pZ and sig.level
from their default values.
The user may also supply one of {kappa, N, power, pi, tau} as a vector of values to perform multiple power calculations at a time,
in which case the target parameter will be calculated for that entire vector.
If effect.size = FALSE, omega represents the reference within-assignment-group standard deviation of the outcome. The user may wish to
use an estimate of the standard deviation of the outcome prior to the intervention (i.e. in the absence of the treatment).
See "Discussion on Effect Sizes" section in Bansak (2020) for more information and guidance.
The assume.ord.means argument allows the user to choose whether or not to make the ordered means assumption, presented and described in Bansak (2020).
Users should only make this assumption (i.e. set assume.ord.means = TRUE) if they are reasonably confident that it will be met in their context of interest.
See "Narrowing the Bounds" section in Bansak (2020) for more information and guidance.
Value
A list that includes the values of the input parameters supplied by the user (input.parameter) and the corresponding output value(s)
of the target parameter (output.parameter).
Note also that the results along with additional information will be displayed in the console if verbose = TRUE.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
Examples
#EXAMPLE 1
#Recovering power, without ordered-means assumption
#powerLATE(pi = 0.5, N = 3000, kappa = 0.25)
results <- powerLATE(pi = 0.5, N = 3000, kappa = 0.25)
results$input.parameter
results$output.parameter
#EXAMPLE 2
#Recovering power for various compliance rates,
#without ordered-means assumption, and with unequal treatment-assignment probability
powerLATE(pZ = 0.25, pi = c(0.3,0.4,0.5,0.6,0.7), N = 3000, kappa = 0.25)
#EXAMPLE 3
#Again recovering power for various compliance rates,
#this time with the ordered-means assumption
powerLATE(pi = c(0.3,0.4,0.5,0.6,0.7), N = 3000, kappa = 0.25,
assume.ord.means = TRUE)
#EXAMPLE 4
#Recovering power, without ordered-means assumption,
#this time using absolute effect rather than effect size
powerLATE(pi = 0.5, N = 3000,
effect.size = FALSE, tau = 300, omega = 1500)
#EXAMPLE 5
#Recovering required sample size for various compliance rates,
#with ordered-means assumption
powerLATE(pi = c(0.5,0.6,0.7,0.8), kappa = 0.25,
power = 0.8, assume.ord.means = TRUE)
#EXAMPLE 6
#Recovering required sample size for various compliance rates,
#with ordered-means assumption, and specifying absolute effect
powerLATE(pi = c(0.5,0.6,0.7,0.8),
power = 0.8, assume.ord.means = TRUE,
effect.size = FALSE, tau = 25, omega = 125)
#EXAMPLE 7
#Recovering minimum detectable effect size for various sample sizes,
#without ordered-means assumption
powerLATE(pi = 0.6, N = c(1000,1500,2000,2500,3000),
power = 0.8)
#EXAMPLE 8
#Recovering minimum detectable effect (absolute) for various sample sizes,
#with ordered-means assumption, and with unequal treatment-assignment probability
powerLATE(pZ = 0.4, pi = 0.6, N = c(1000,1500,2000,2500,3000),
power = 0.8, assume.ord.means = TRUE,
effect.size = FALSE, omega = 50)
Generalized Power Analysis for LATE wth covariates
Description
Function to perform generalized power analysis for the LATE (i.e. under noncompliance with treatment assignment), allowing for covariate adjustment. Function allows for user to work with either standardized effect sizes or absolute effects. The results provided presume a test of the null hypothesis that the LATE equals 0 with a two-sided alternative.
Usage
powerLATE.cov(pZ = 0.5, pi, N, kappa,
sig.level = 0.05, power,
effect.size = TRUE, tau = NULL, omega = NULL,
assume.ord.means = FALSE, r2dw, r2yw, verbose = TRUE)
Arguments
pZ |
probability of being assigned to treatment. Default is 0.5, i.e. equal assignment probability. |
pi |
compliance rate. Equivalently, average causal effect of treatment assignment on treatment uptake. |
N |
total sample size. |
kappa |
LATE effect size (i.e. effect size for compliers). |
sig.level |
significance level (Type I error probability). Default is 0.05. |
power |
power of test (1 minus Type II error probability). |
effect.size |
whether effect size (kappa) rather than absolute effect (tau) is used in power calculations. Default is |
tau |
LATE absolute effect (i.e. absolute effect for compliers). Must only be supplied if |
omega |
within-group standard deviation of the outcome. Must be supplied if |
assume.ord.means |
whether ordered means assumption is made. Default is |
r2dw |
proportion of variation in D left unexplained by Z that is explained by W. |
r2yw |
proportion of variation in Y left unexplained by Z that is explained by W. |
verbose |
print input and output parameter values. Default is |
Details
If effect.size = TRUE (the default setting), exactly two of the parameters {kappa, N, power} must be supplied,
from which the third (target) parameter will be calculated. If effect.size = FALSE, omega must be supplied, and exactly two of
the parameters {tau, N, power} must be supplied. pi must always be supplied, and the user can change pZ and sig.level
from their default values.
Values between 0 and 1 must also be supplied for r2dw and r2yw. See "Power with Covariates) section in Bansak (2020) for more information and guidance.
The user may also supply one of {kappa, N, power, pi, tau, r2dw, r2yw} as a vector of values to perform multiple power calculations at a time,
in which case the target parameter will be calculated for that entire vector.
If effect.size = FALSE, omega represents the reference within-assignment-group standard deviation of the outcome. The user may wish to
use an estimate of the standard deviation of the outcome prior to the intervention (i.e. in the absence of the treatment).
See "Discussion on Effect Sizes" section in Bansak (2020) for more information and guidance.
The assume.ord.means argument allows the user to choose whether or not to make the ordered means assumption, presented and described in Bansak (2020).
Users should only make this assumption (i.e. set assume.ord.means = TRUE) if they are reasonably confident that it will be met in their context of interest.
See "Narrowing the Bounds" section in Bansak (2020) for more information and guidance.
Value
A list that includes the values of the input parameters supplied by the user (input.parameter) and the corresponding output value(s)
of the target parameter (output.parameter).
Note also that the results along with additional information will be displayed in the console if verbose = TRUE.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
Examples
#EXAMPLE 1
#Recovering power, without ordered-means assumption
#powerLATE.cov(pi = 0.5, N = 3000, kappa = 0.25, r2dw = 0.15, r2yw = 0.10)
results <- powerLATE.cov(pi = 0.5, N = 3000, kappa = 0.25,
r2dw = 0.15, r2yw = 0.10)
results$input.parameter
results$output.parameter
#EXAMPLE 2
#Recovering power for various compliance rates,
#without ordered-means assumption, and with unequal treatment-assignment probability
powerLATE.cov(pZ = 0.25, pi = c(0.3,0.4,0.5,0.6,0.7), N = 3000,
kappa = 0.25, r2dw = 0.15, r2yw = 0.10)
#EXAMPLE 3
#Again recovering power for various compliance rates,
#this time with the ordered-means assumption
powerLATE.cov(pi = c(0.3,0.4,0.5,0.6,0.7), N = 3000, kappa = 0.25,
assume.ord.means = TRUE, r2dw = 0.15, r2yw = 0.10)
#EXAMPLE 4
#Recovering power, without ordered-means assumption,
#this time using absolute effect rather than effect size
powerLATE.cov(pi = 0.5, N = 3000, effect.size = FALSE,
tau = 300, omega = 1500, r2dw = 0.15, r2yw = 0.10)
#EXAMPLE 5
#Recovering required sample size for various compliance rates,
#with ordered-means assumption
powerLATE.cov(pi = c(0.5,0.6,0.7,0.8), kappa = 0.25, power = 0.8,
assume.ord.means = TRUE, r2dw = 0.15, r2yw = 0.10)
#EXAMPLE 6
#Recovering required sample size for various compliance rates,
#with ordered-means assumption, and specifying absolute effect
powerLATE.cov(pi = c(0.5,0.6,0.7,0.8), power = 0.8,
assume.ord.means = TRUE, effect.size = FALSE, tau = 25,
omega = 125, r2dw = 0.15, r2yw = 0.10)
#EXAMPLE 7
#Recovering minimum detectable effect size for various sample sizes,
#without ordered-means assumption
powerLATE.cov(pi = 0.6, N = c(1000,1500,2000,2500,3000),
power = 0.8, r2dw = 0.15, r2yw = 0.10)
#EXAMPLE 8
#Recovering minimum detectable effect (absolute) for various sample sizes,
#with ordered-means assumption, and with unequal treatment-assignment probability
powerLATE.cov(pZ = 0.4, pi = 0.6, N = c(1000,1500,2000,2500,3000),
power = 0.8, assume.ord.means = TRUE,
effect.size = FALSE, omega = 50, r2dw = 0.15, r2yw = 0.10)
Print Function for powerLATE
Description
Print output for powerLATE and powerLATE.cov.
Usage
## S3 method for class 'powerLATE'
print(x, ...)
Arguments
x |
List of message.input, message.output, res, note to be printed |
... |
Further arguments to be passed to |
Value
strings and a dataframe for output.
Note
This function is called internally and should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
Subsidiary PowerLATE Function
Description
Subsidiary function to perform power calculation under unequal assignment probability and ordered mean assumption.
Usage
unequal.ordered(
power = NULL,
sig.level = NULL,
pi = NULL,
kappa = NULL,
N = NULL,
pZ = NULL
)
Arguments
power |
power of test (1 minus Type II error probability) |
sig.level |
significance level (Type I error probability). |
pi |
compliance rate. Equivalently, average causal effect of Z on D. |
kappa |
effect size |
N |
total number of observations |
pZ |
probability of being assigned to treatment. |
Value
A vector of values for one in {kappa, N, power} that is not supplied by the user.
Note
This function is called internally and thus should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
See Also
equal.unordered, equal.ordered, unequal.unordered.
Subsidiary powerLATE Function
Description
Subsidiary function to perform power calculation with covariates under unequal assignment probability with ordered mean assumption.
Usage
unequal.ordered.cov(
power = NULL,
sig.level = NULL,
pi = NULL,
kappa = NULL,
N = NULL,
pZ = NULL,
r2dw = NULL,
r2yw = NULL
)
Arguments
power |
power of test (1 minus Type II error probability) |
sig.level |
significance level (Type I error probability). |
pi |
compliance rate. Equivalently, average causal effect of Z on D. |
kappa |
effect size |
N |
total number of observations |
pZ |
probability of being assigned to treatment. |
r2dw |
proportion of variation in D left unexplained by Z that is explained by W. |
r2yw |
proportion of variation in Y left unexplained by Z that is explained by W. |
Value
A vector of values for one in {kappa, N, power} that is not supplied by the user.
Note
This function is called internally and thus should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
See Also
equal.unordered.cov, equal.ordered.cov, unequal.unordered.cov.
Subsidiary PowerLATE Function
Description
Subsidiary function to perform power calculation under unequal assignment probability and without ordered mean assumption.
Usage
unequal.unordered(
power = NULL,
sig.level = NULL,
pi = NULL,
kappa = NULL,
N = NULL,
pZ = NULL
)
Arguments
power |
power of test (1 minus Type II error probability) |
sig.level |
significance level (Type I error probability). |
pi |
compliance rate. Equivalently, average causal effect of Z on D. |
kappa |
effect size |
N |
total number of observations |
pZ |
probability of being assigned to treatment. |
Value
A vector of values for one in {kappa, N, power} that is not supplied by the user.
Note
This function is called internally and thus should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
See Also
equal.unordered, equal.ordered, unequal.ordered.
Subsidiary powerLATE Function
Description
Subsidiary function to perform power calculation with covariates under unequal assignment probability without ordered mean assumption.
Usage
unequal.unordered.cov(
power = NULL,
sig.level = NULL,
pi = NULL,
kappa = NULL,
N = NULL,
pZ = NULL,
r2dw = NULL,
r2yw = NULL
)
Arguments
power |
power of test (1 minus Type II error probability) |
sig.level |
significance level (Type I error probability). |
pi |
compliance rate. Equivalently, average causal effect of Z on D. |
kappa |
effect size |
N |
total number of observations |
pZ |
probability of being assigned to treatment. |
r2dw |
proportion of variation in D left unexplained by Z that is explained by W. |
r2yw |
proportion of variation in Y left unexplained by Z that is explained by W. |
Value
A vector of values for one in {kappa, N, power} that is not supplied by the user.
Note
This function is called internally and thus should not be used directly.
Author(s)
Kirk Bansak and Eddie Yang
References
Bansak, K. (2020). A Generalized Approach to Power Analysis for Local Average Treatment Effects. Statistical Science, 35(2), 254-271.
See Also
equal.unordered.cov, equal.ordered.cov, unequal.ordered.cov.