Package 'powerLATE'

Title: Generalized Power Analysis for LATE
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.
Authors: Kirk Bansak [aut], Eddie Yang [aut, cre]
Maintainer: Eddie Yang <[email protected]>
License: GPL (>= 2)
Version: 0.1.2
Built: 2025-02-12 03:54:52 UTC
Source: https://github.com/kbansak/powerlate

Help Index


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 TRUE.

tau

LATE absolute effect (i.e. absolute effect for compliers). Must only be supplied if effect.size = FALSE.

omega

within-group standard deviation of the outcome. Must be supplied if effect.size = FALSE. See Details.

assume.ord.means

whether ordered means assumption is made. Default is FALSE. See Details.

verbose

print input and output parameter values. Default is TRUE.

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 TRUE.

tau

LATE absolute effect (i.e. absolute effect for compliers). Must only be supplied if effect.size = FALSE.

omega

within-group standard deviation of the outcome. Must be supplied if effect.size = FALSE. See Details.

assume.ord.means

whether ordered means assumption is made. Default is FALSE. See Details.

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 TRUE.

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 print.powerLATE().

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.