| Title: | Hypothesis Testing in Cluster-Randomized Encouragement Designs |
|---|---|
| Description: | An implementation of randomization-based hypothesis testing for three different estimands in a cluster-randomized encouragement experiment. The three estimands include (1) testing a cluster-level constant proportional treatment effect (Fisher's sharp null hypothesis), (2) pooled effect ratio, and (3) average cluster effect ratio. To test the third estimand, user needs to install 'Gurobi' (>= 9.0.1) optimizer via its R API. Please refer to <https://www.gurobi.com/documentation/9.0/refman/ins_the_r_package.html>. |
| Authors: | Bo Zhang |
| Maintainer: | Bo Zhang <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.0 |
| Built: | 2024-12-09 06:42:18 UTC |
| Source: | CRAN |
ACER tests (two-sided) if the average cluster effect
ratio (ACER) is equal to lambda.
ACER( num_t, num_c, R_t, R_c, d_t, d_c, lambda, alpha = 0.05, kappa = 0.1, gap = 0.05, verbose = TRUE )ACER( num_t, num_c, R_t, R_c, d_t, d_c, lambda, alpha = 0.05, kappa = 0.1, gap = 0.05, verbose = TRUE )
num_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the number of units in the encouraged cluster of the kth matched pair of two clusters. |
num_c |
A length-K vector with the kth entry equal to the number of units in the control cluster of the kth matched pair of two clusters. |
R_t |
A length-K vector with kth entry equal to the sum of unit-level outcomes in the encouraged cluster of the kth matched pair of two clusters. |
R_c |
A length-K vector with the kth entry equal to the sum of unit-level outcomes in the control cluster of the kth matched pair of two clusters. |
d_t |
A length-K vector with the kth entry equal to the sum of unit-level treatment received in the encouraged cluster of the kth matched pair of two clusters. |
d_c |
A length-K vector with the kth entry equal to the sum of unit-level treatment received in the control cluster of the kth matched pair of two clusters. |
lambda |
The magnitude of the average cluster effect ratio (ACER) to be tested. |
alpha |
The level of the test. |
kappa |
Minimum compliance rate. |
gap |
Relative MIP optimality gap. |
verbose |
If true, the solver output is enabled; otherwise, the solver output is disabled. |
A list of three elements: the optimal solution, the optimal objective value, and an indicator of whether or not the test is rejected.
## Not run: # To run the following example, Gurobi must be installed. R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment num_t = encouraged_clusters$number_units num_c = control_clusters$number_units # Test at level 0.05 if the ACER is equal # to 0.2. Assume the minimum compliance rate across # K clusters is at least 0.2. Set verbose = FALSE # to suppress the output. res = ACER(num_t, num_c, R_t, R_c, d_t, d_c, lambda = 0.2, alpha = 0.05, kappa = 0.2, verbose = FALSE) # The test is rejected res$Reject ## End(Not run)## Not run: # To run the following example, Gurobi must be installed. R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment num_t = encouraged_clusters$number_units num_c = control_clusters$number_units # Test at level 0.05 if the ACER is equal # to 0.2. Assume the minimum compliance rate across # K clusters is at least 0.2. Set verbose = FALSE # to suppress the output. res = ACER(num_t, num_c, R_t, R_c, d_t, d_c, lambda = 0.2, alpha = 0.05, kappa = 0.2, verbose = FALSE) # The test is rejected res$Reject ## End(Not run)
A dataset containing the covariates, aggregated outcome,
aggregated treatment received, number of units, and the
cluster-level IV of 100 matched control clusters. There is
a one-to-one correspondence between this 100 matched
control clusters and 100 matched encouraged clusters: the kth
control cluster is matched to the kth encouraged cluster in
encouraged_clusters.
control_clusterscontrol_clusters
A data frame with 100 rows and 14 columns:
1st simulated covariate
2nd simulated covariate
3rd simulated covariate
4th simulated covariate
5th simulated covariate
6th simulated covariate
7th simulated covariate
8th simulated covariate
9th simulated covariate
10th simulated covariate
Total number of death in the cluster
Total number of treatment received
Number of units in each cluster
Cluster-level instrumental variable
This is a simulated dataset.
double_rank returns the two-sided p-value testing
Fisher's sharp null hypothesis in a cluster-level proportional
treatment effect model.
double_rank(beta_0, R_t, R_c, d_t, d_c, Z_t, Z_c, psi = NULL)double_rank(beta_0, R_t, R_c, d_t, d_c, Z_t, Z_c, psi = NULL)
beta_0 |
The magnitude of the proportional treatment effect to be tested. |
R_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level outcomes in the encouraged cluster of the kth matched pair of two clusters. |
R_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level outcomes in the control cluster of the kth matched pair of two clusters. |
d_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level treatment received in the encouraged cluster of the kth matched pair of two clusters. |
d_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level treatment received in the control cluster of the kth matched pair of two clusters. |
Z_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the encoruagement dose, i.e., the magnitude of the instrumental variable, of the encouraged cluster in the kth matched pair of two clusters. |
Z_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the encoruagement dose, i.e., the magnitude of the instrumental variable, of the control cluster in the kth matched pair of two clusters. |
psi |
A function specifying the score used in the test statistic. See Details. |
Double-rank test statistics is a flexible family of nonparametric
test statistics. Function psi is a function that specifies
the relationship between d_k, the normalized rank of the absolute
treated-minus-control dose difference in the instrumental variable,
and q_k, the normalized rank of the absoluve treated-minus-control
dose difference in the observed outcome. For instance, psi(d_k, q_k)
= 1 yields the sign test, psi(d_k, q_k) = q_k yields the Wilcoxon
signed rank test. The default setting, psi(d_k, q_k) = d_k * q_k, yields
the dose-weighted signed rank test.
A list of five elements: two-sided p-value, deviate, test statistics, expectation of the test statistic under the null hypothesis, and variance of the test statistic under the null hypothesis.
R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment Z_t = encouraged_clusters$IV Z_c = control_clusters$IV # Test beta = 0 in the proportional treatment effect # model with the help of the double rank test using # default psi(d_k, q_k) = d_k * q_k: res = double_rank(0, R_t, R_c, d_t, d_c, Z_t, Z_c) # Define a new psi function: psi(d_k, q_k) = q_k psi_2 <- function(x, y) y # Using psi_2 and the double rank test is reduced to the #Wilcoxon signed rank test. res_2 = double_rank(0, R_t, R_c, d_t, d_c, Z_t, Z_c, psi = psi_2)R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment Z_t = encouraged_clusters$IV Z_c = control_clusters$IV # Test beta = 0 in the proportional treatment effect # model with the help of the double rank test using # default psi(d_k, q_k) = d_k * q_k: res = double_rank(0, R_t, R_c, d_t, d_c, Z_t, Z_c) # Define a new psi function: psi(d_k, q_k) = q_k psi_2 <- function(x, y) y # Using psi_2 and the double rank test is reduced to the #Wilcoxon signed rank test. res_2 = double_rank(0, R_t, R_c, d_t, d_c, Z_t, Z_c, psi = psi_2)
double_rank_CI returns the two-sided level-alpha confidence
interval of the proportional treatment effect in a cluster-level
proportional treatment effect model.
double_rank_CI( R_t, R_c, d_t, d_c, Z_t, Z_c, lower, upper, meshsize = 0.001, psi = NULL, alpha = 0.05 )double_rank_CI( R_t, R_c, d_t, d_c, Z_t, Z_c, lower, upper, meshsize = 0.001, psi = NULL, alpha = 0.05 )
R_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level outcomes in the encouraged cluster of the kth matched pair of two clusters. |
R_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level outcomes in the control cluster of the kth matched pair of two clusters. |
d_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level treatment received in the encouraged cluster of the kth matched pair of two clusters. |
d_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level treatment received in the control cluster of the kth matched pair of two clusters. |
Z_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the encoruagement dose, i.e., the magnitude of the instrumental variable, of the encouraged cluster in the kth matched pair of two clusters. |
Z_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the encoruagement dose, i.e., the magnitude of the instrumental variable, of the control cluster in the kth matched pair of two clusters. |
lower, upper
|
The lower and upper endpoints of the interval to be searched. |
meshsize |
The meshsize of the grid search. |
psi |
A function specifying the score used in the test statistic.
See Details of |
alpha |
The level of the confidence interval. |
double_rank_CI constructs a two-sided level-alpha confidence interval
by interting the hypothesis test using a double_rank test. Function
double_rank_CI conducts a grid search with user-specified endpoints
and meshsize in order to construct the confidence interval. For more
details on the double_rank test, see double_rank.
A length-2 vector of two endpoints of the confidence interval.
R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment Z_t = encouraged_clusters$IV Z_c = control_clusters$IV # Construct a level 0.05 CI for the constant proportional # treatment effect with the help of the double rank test using # default psi(d_k, q_k) = d_k * q_k. Search from -0.1 to 0.1: CI = double_rank_CI(R_t, R_c, d_t, d_c, Z_t, Z_c, lower = -0.1, upper = 0.1)R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment Z_t = encouraged_clusters$IV Z_c = control_clusters$IV # Construct a level 0.05 CI for the constant proportional # treatment effect with the help of the double rank test using # default psi(d_k, q_k) = d_k * q_k. Search from -0.1 to 0.1: CI = double_rank_CI(R_t, R_c, d_t, d_c, Z_t, Z_c, lower = -0.1, upper = 0.1)
A dataset containing the covariates, aggregated outcome,
aggregated treatment received, number of units, and the
cluster-level IV of 100 matched encouraged clusters. There is
a one-to-one correspondence between this 100 matched
encouraged clusters and 100 matched control clusters: the kth
encouraged cluster is matched to the kth control cluster in
control_clusters.
encouraged_clustersencouraged_clusters
A data frame with 100 rows and 14 columns:
1st simulated covariate
2nd simulated covariate
3rd simulated covariate
4th simulated covariate
5th simulated covariate
6th simulated covariate
7th simulated covariate
8th simulated covariate
9th simulated covariate
10th simulated covariate
Total number of death in the cluster
Total number of treatment received
Number of units in each cluster
Cluster-level instrumental variable
This is a simulated dataset.
PER returns the two-sided p-value testing
the pooled effect ratio equal to lambda_0 in a cluster-randomized
encouragement experiment.
PER(lambda_0, R_t, R_c, d_t, d_c, Q = NULL)PER(lambda_0, R_t, R_c, d_t, d_c, Q = NULL)
lambda_0 |
The magnitude of the pooled effect ratio estimand to be tested. |
R_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level outcomes in the encouraged cluster of the kth matched pair of two clusters. |
R_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level outcomes in the control cluster of the kth matched pair of two clusters. |
d_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level treatment received in the encouraged cluster of the kth matched pair of two clusters. |
d_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level treatment received in the control cluster of the kth matched pair of two clusters. |
Q |
A K times p design matrix containing the covariate information. See Details. |
Q is used to construct a regression-assisted variance estimator. Q is can in principle be any K times p design matrix such that p < K. When Q is a column vector of 1's, the variance estimator is the classical sample variance estimator. More generally, Q may contain any cluster-level or even unit-level covariate information that are predictive of the encouraged-minus-control difference in the observed aggregated outcomes.
A list of five elements: two-sided p-value, deviate, test statistics, expectation of the test statistic under the null hypothesis, and variance of the test statistic under the null hypothesis.
R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment # Test the pooled effect ratio estimand lambda = 0 using # the default sample variance estimator, i.e., setting Q = NULL. res = PER(0, R_t, R_c, d_t, d_c) # We may leverage observed covariates from both the encouraged # and control clusters to construct less conservative variance # estimator. The variance estimator will be less conservative if # these covariate predict the treated-minus-control difference # in the outcome. In this illustrated dataset, V1-V10 are simulated # white noise; it is not surprising that they do not help # reduce the variance. Q = cbind(encouraged_clusters[,1:10], control_clusters[,1:10]) res_2 = PER(0, R_t, R_c, d_t, d_c, Q)R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment # Test the pooled effect ratio estimand lambda = 0 using # the default sample variance estimator, i.e., setting Q = NULL. res = PER(0, R_t, R_c, d_t, d_c) # We may leverage observed covariates from both the encouraged # and control clusters to construct less conservative variance # estimator. The variance estimator will be less conservative if # these covariate predict the treated-minus-control difference # in the outcome. In this illustrated dataset, V1-V10 are simulated # white noise; it is not surprising that they do not help # reduce the variance. Q = cbind(encouraged_clusters[,1:10], control_clusters[,1:10]) res_2 = PER(0, R_t, R_c, d_t, d_c, Q)
PER_CI returns the two-sided level-alpha confidence
interval of the pooled effect ratio in a cluster-randomized
encouragement experiment.
PER_CI( R_t, R_c, d_t, d_c, lower, upper, Q = NULL, meshsize = 0.001, alpha = 0.05 )PER_CI( R_t, R_c, d_t, d_c, lower, upper, Q = NULL, meshsize = 0.001, alpha = 0.05 )
R_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level outcomes in the encouraged cluster of the kth matched pair of two clusters. |
R_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level outcomes in the control cluster of the kth matched pair of two clusters. |
d_t |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level treatment received in the encouraged cluster of the kth matched pair of two clusters. |
d_c |
A length-K vector where K is equal to the number of clusters and the kth entry equal to the sum of unit-level treatment received in the control cluster of the kth matched pair of two clusters. |
lower, upper
|
The lower and upper endpoints of the interval to be searched. |
Q |
A K times p design matrix containing the covariate information.
See Details of the function |
meshsize |
The meshsize of the grid search. |
alpha |
The level of the confidence interval. |
PER_CI constructs a two-sided level-alpha confidence interval
by interting the corresponding hypothesis test for the pooled effect
ratio. See PER for details on the hypothesis tesing.
PER_CI conducts a grid search with user-specified endpoints
and meshsize in order to construct the confidence interval.
A length-2 vector of two endpoints of the confidence interval.
R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment # Construct 95% CI for the pooled effect ratio estimand # using the default sample variance estimator, i.e., # setting Q = NULL. CI = PER_CI(R_t, R_c, d_t, d_c, lower = -0.1, upper = 0.1, alpha = 0.05)R_t = encouraged_clusters$aggregated_outcome R_c = control_clusters$aggregated_outcome d_t = encouraged_clusters$aggregated_treatment d_c = control_clusters$aggregated_treatment # Construct 95% CI for the pooled effect ratio estimand # using the default sample variance estimator, i.e., # setting Q = NULL. CI = PER_CI(R_t, R_c, d_t, d_c, lower = -0.1, upper = 0.1, alpha = 0.05)