Description Usage Arguments Details Value Examples
View source: R/calc.H2x2Factorial.R
The function calc.H2x2Factorial
estimates the required number of clusters or the achieved power level under different types of
hypothesis tests of either the controlled (main) effect (by default) or the natural (marginal) effect of the two treatments in a hierarchical 2x2 factorial trial
with unequal cluster sizes and a continuous outcome. Two types of treatment effect estimands, five types of hypothesis tests as well as their corresponding
finitesample considerations could be chosen for the predictions. Users may input an optional cluster number through the n.input
argument. When this
number is provided, the function will calculate the power under a chosen hypothesis test as well as a finitesample correction if specified, and the function
will ignore the potential input for the power parameter; When the number of clusters is not provided, the function will calculate the required number of
clusters based on a given power threshold, which is set to 0.8 by default.
1 2 3 4 5 6 7 
power 
a numeric value between 0 and 1 as the desired power level for sample size estimation. Default is 
n_input 
a number of cluster provided by the user to estimate the power that can be achieved. Default is 
alpha 
a numeric value between 0 and 1 as the type I error rate. Default is 
pi_x 
a numeric value between 0 and 1 as the proportion of clusters randomized to the clusterlevel treatment. Default is 
pi_z 
a numeric value between 0 and 1 as the proportion of individuals randomized to the individuallevel treatment within each cluster. Default is 
delta_x 
a nonzero numeric value for the (unstandardized) effect size of the marginal clusterlevel treatment effect. Default is 
delta_z 
a nonzero numeric value for the (unstandardized) effect size of the marginal individuallevel treatment effect. Default is 
delta_xz 
a nonzero numeric value for the (unstandardized) effect size of the interaction effect of the two treatments. Default is 
sigma2_y 
a positive numeric value for the total variance of the continuous outcome. Default is 
m_bar 
a numeric value larger than 2 for the mean cluster size. Default is 
CV 
a positive numeric value as the coefficient of variation of the cluster sizes. Default is 
rho 
a numeric value between 0 and 1 as the intraclass correlation coefficient characterizing the betweencluster variability. Default is 
estimand 
a character argument indicating the type of treatment effect estimand. Supported values include 
test 
a character argument indicating the type of hypothesis test of interest. Supported values include

correction 
a logical argument indicating whether a finite sample correction should be used. Default is 
max_n 
an optional setting of a maximum number of clusters, which is only functional under 
seed_mix 
an optional setting of a seed for conducting the simulationbased testing under a mixed distribution, which is only functional under 
size_mix 
a prespecified size for the mixed distribution in the simulationbased procedure, which is only needed under 
verbose 
a logical argument indicating whether the parameter reiterations and supplementary messages should be presented or suppressed. Default is 
Given the input parameters, our method will firstly compute the variances of the effects of interest based on Generalized Least Square estimators and largesample approximations.
Then, the variances are used to build up either the classic sample size formulas (for the separate tests for controlled or natural treatment effects and the interaction test) or
the power formulas (for the simultaneous tests and the corrected tests), which help to deliver both the sample size and power calculations.
Without finitesample considerations, the separate tests of the two controlled effects and the two natural effects as well as the interaction test use the twosided Wald ztest,
the joint test use the Chisquare test, and the intersectionunion (IU) test use also a twosided zbased test.
With correction=T
, finitesample corrections are customized for the three types of tests involving either the controlled effect or the natural effect of the clusterlevel
treatment: For the tests for the controlled effect and the natural effect of the clusterlevel treatment, a twosided ttest is used;
For the joint test of the two controlled effects, a Ftest is used as a naive correction, which might lead to slight overpower;
For the joint test of the two natural effects, a simulationbased mixed Fchisquare test is used;
For the IU test of the two controlled effects, a twosided tbased test is used as a naive correction, which might lead to slight overpower.
For the IU test of the two natural effects, a twosided mixed t and zbased test is used.
For the finitesample corrected joint test of the two natural effects, since there does not exist the required parametric distribution, we offer a simulationbased method to
generate the null and alternative distributions, and we use the simulated distributions to compute the power and required sample size.
A seed should be set via seed_mix
for this random process to promote reproducibility, and this is only needed under the natural effect joint test with finitesample correction.
The two types of estimand
, the five types of test
, and the developments of correction
are defined in Tian et al. (under review).
calc.H2x2Factorial
returns an integer representing the required number of clusters or a decimal representing the power that can be achieved by the provided
sample size, with some useful and suppressible messages elaborating vital parameter choices and results (the power will be displayed in 4 decimal places; the messages can be suppressed via verbose=FALSE
).
1 2 3 4 5 6 7 8  #Predict the actual power of a natural effect joint test when the number of clusters is 10
joint.power < calc.H2x2Factorial(n_input=10,
delta_x=0.2, delta_z=0.1,
rho=0.1, CV=0.38,
estimand="natural",
test="joint",
correction=TRUE, seed_mix=123456, verbose=FALSE)
print(joint.power)

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.