critical.value {hrt} | R Documentation |
Critical Values for Heteroskedasticity Robust Testing
Description
This function provides an implementation of
Algorithm 3 in Pötscher and Preinerstorfer (2021), based on
Algorithm 1 (if q=1
) or Algorithm 2
(if q>1
) in the same reference as the auxiliary algorithm A
.
Which of the two algorithms is used is automatically
determined as a function of q
, the number of rows of R
.
The user is referred to
Pötscher and Preinerstorfer (2021) for definitions,
a detailed description of the problems solved
by the algorithms, and for a detailed description of the algorithms themselves.
Most of the input parameters to critical.value
are actually used
in the auxiliary Algorithm 1 or 2, respectively.
Algorithm 1 is based on the function
davies
from the package CompQuadForm. The parameters
lim
and acc
for davies
can be supplemented by the user.
Algorithms 1 and 2 are implemented using the function constrOptim
from stats in Stages 1 and 2; this function
is used with default parameters, but control parameters can be supplied by the user.
After determining a critical value for a given testing
problem via the function critical.value
, it is recommended that: (i) the user
applies the function size
to compute the size of the test corresponding to the critical value obtained;
and (ii) to check whether the size obtained does coincide with (or is close to) the targeted level of
significance (that is alpha
). If (ii) is not the case, this is an indication
of numerical issues, which potentially can be avoided by changing the input parameters
responsible for the accuracy of the computations.
Usage
critical.value(alpha, R, X, hcmethod, restr.cov, Mp, M1, M2,
N0 = NULL, N1 = NULL, N2 = NULL, tol = 1e-08,
control.1 = list("reltol" = 1e-02, "maxit" = dim(X)[1]*20),
control.2 = list("reltol" = 1e-03, "maxit" = dim(X)[1]*30),
cores = 1, lower = 0, eps.close = .0001, lim = 30000, acc = 0.001,
size.tol = .001, maxit = 25, as.tol = 1e-08)
Arguments
alpha |
Significance level. A real number in the interval (0,1) .
|
R |
The restriction matrix. critical.value computes the (smallest) size-controlling critical value
for a test of the hypothesis Rβ=r . R needs to be of
full row rank, and needs to have the same number of columns as X .
|
X |
The design matrix X needs to be of full column rank.
The number of columns of X must be smaller than the number of rows of
X .
|
hcmethod |
Integer in [-1, 4]. Determines the method applied in the construction of the covariance estimator
used in the test statistic. The value -1 corresponds to unadjusted (i.e., classical) F statistic without df adjustment; the value 0
corresponds to the HC0 estimator; ...; the value 4 corresponds to the HC4 estimator. Note that in case restr.cov
is TRUE the null-restricted versions of the covariance estimators are computed. Cf. Pötscher
and Preinerstorfer (2021) and the references there for details.
|
restr.cov |
TRUE or FALSE. Covariance matrix estimator based on null-restricted (TRUE) or unrestricted (FALSE) residuals.
|
Mp |
This input is used in Algorithm 1 or 2, respectively. Mp is a positive integer
(should be chosen large, e.g., 50000; but the feasibility depends on the dimension of X , etc).
Mp determines M0 in Algorithm 1 or 2 (i.e., A ), respectively, that is,
the number of initial values chosen in Stage 0 of that algorithm. The way initial values
(i.e., the sets of variance covariance matrices Σj in Stage 0 of the algorithm;
the diagonal entries of each Σj sum up to 1) are chosen is as follows:
If q=1 and lower=0 , one of the initial values Σj is a matrix which maximizes the expectation of the quadratic form y↦y′Σ1/2ACΣ1/2y under an n-variate standard normal distribution. Here, AC is a matrix that is defined Pötscher and Preinerstorfer (2021).
If diagonal entries of this maximizer are 0, then they are replaced by the value of eps.close (and the other values are adjusted
so that the diagonal sums up to 1).
One starting value Σj is a diagonal matrix with constant diagonal entries.
If lower is zero, then (i) ⌈Mp/4⌉−1 covariance matrices Σj are drawn by sampling their diagonals τ12,...,τn2 from a uniform distribution
on the unit simplex in Rn ; and (ii) the remaining Mp−(⌈Mp/4⌉−1) covariance matrices Σj are each drawn by first sampling a vector (t1,...,tn)′ from a uniform distribution
on the unit simplex in Rn , and by then obtaining the diagonal τ12,...,τn2 of Σj via (t12,...,tn2)/∑i=1nti2 . If lower is nonzero,
then the initial values are drawn analogously, but from a uniform distribution on the subset of the unit simplex in Rn corresponding to the restriction imposed
by the lower bound lower .
-
n starting values equal to covariance matrices with a single dominant diagonal entry and all other diagonal entries constant. The size of the dominant
diagonal entry is regulated via the input parameters eps.close and lower . In case lower is nonzero,
the size of the dominant diagonal entry equals 1−(n−1)∗(lower+eps.close) . In case lower is zero, the size of the dominant diagonal
entry equals 1−eps.close .
|
M1 |
This input is used in Algorithm 1 or 2, respectively. A positive integer
(should be chosen large, e.g., 500; but the feasibility depends on the dimension of X , etc).
Corresponds to M1 in the description of
Algorithm 1 and 2 in
Pötscher and Preinerstorfer (2021). M1 must not exceed Mp.
|
M2 |
This input is used in Algorithm 1 or 2, respectively.
A positive integer. Corresponds to M2 in the description of
Algorithm 1 and 2 in
Pötscher and Preinerstorfer (2021). M2 must not exceed M1.
|
N0 |
This input is needed in Algorithm 2.
Only used in case q>1 (i.e., when Algorithm 2 is used). A positive integer.
Corresponds to N0 in the description of Algorithm 2 in
Pötscher and Preinerstorfer (2021).
|
N1 |
This input is needed in Algorithm 2.
Only used in case q>1 (i.e., when Algorithm 2 is used). A positive integer.
Corresponds to N1 in the description of Algorithm 2 in
Pötscher and Preinerstorfer (2021). N1 should be greater than
N0.
|
N2 |
This input is needed in Algorithm 2.
Only used in case q>1 (i.e., when Algorithm 2 is used). A positive integer.
Corresponds to N2 in the description of Algorithm 2 in
Pötscher and Preinerstorfer (2021). N2 should be greater than
N1.
|
tol |
This input is used in Algorithm 1 or 2, respectively.
(Small) positive real number. Tolerance parameter used in checking invertibility of the
covariance matrix in the test statistic. Default is 1e-08.
|
control.1 |
This input is used in Algorithm 1 or 2, respectively.
Control parameters passed to the constrOptim function in
Stage 1 of Algorithm 1 or 2, respectively. Default is control.1 = list("reltol" = 1e-02,
"maxit" = dim(X)[1]*20) .
|
control.2 |
This input is used in Algorithm 1 or 2, respectively.
Control parameters passed to the constrOptim function in
Stage 2 of Algorithm 1 or 2, respectively. Default is control.2 = list("reltol" = 1e-03,
"maxit" = dim(X)[1]*30) .
|
cores |
The number of CPU cores used in the (parallelized)
computations. Default is 1. Parallelized computation is enabled only
if the compiler used to build hrt supports OpenMP.
|
lower |
Number in [0,n−1) (note that the diagonal of Σ is normalized
to sum up to 1 ; if lower > 0, then lower corresponds to what is denoted τ∗ in
Pötscher and Preinerstorfer (2021)).
lower specifies a lower bound on each diagonal entry of the (normalized) covariance matrix
in the covariance model for which the user wants to obtain a critical value that achieves size control.
If this lower bound is nonzero (which is the non-standard choice), then the size is only computed over all covariance matrices,
which are restricted such that their minimal diagonal entry is not smaller than lower .
The relevant optimization problems in Algorithm 1 and 2 are then carried out only over this
restricted set of covariance matrices. The size will then in general depend on lower .
See the relevant discussions concerning restricted heteroskedastic covariance models in
Pötscher and Preinerstorfer (2021). Default is 0 , which is the
recommended choice, unless there are strong reasons implying a specific lower bound on
the variance in a given application.
|
eps.close |
(Small) positive real number. This determines the size of the dominant entry in the choice of the
initial values as discussed in the description of the input Mp above.
Default is 1e-4.
|
lim |
This input is needed in Algorithm 1. Only used in case q=1 (i.e., when Algorithm 1 is used).
Input parameter for the function davies . Default is 30000.
|
acc |
This input is needed in Algorithm 1. Only used in case q=1 (i.e., when Algorithm 1 is used).
Input parameter for the function davies . Default is 1e-3.
|
size.tol |
(Small) positive real number. ϵ in Algorithm 3. Default is 1e-3.
|
maxit |
Maximum number of iterations in the while loop of Algorithm 3. Default is 25.
|
as.tol |
(Small) positive real number. Tolerance parameter used in checking rank
conditions for verifying Assumptions 1, 2, and for checking a non-constancy condition
on the test statistic in case hcmethod is not −1 and restr.cov is
TRUE. as.tol is also used in the rank computations required for
computing lower bounds for size-controlling critical values.
Furthermore, as.tol is used in checking the sufficient conditions
for existence of a size-controlling critical value provided in Pötscher
and Preinerstorfer(2021). Default is 1e-08.
|
Details
For details see the relevant sections in Pötscher
and Preinerstorfer
(2021), in particular the description of Algorithms 1 and 2 in the Appendix.
Value
The output of critical.value
is the following:
critical.value |
The critical value obtained by Algorithm 3.
|
approximate.size |
The approximate size of the test based on the
returned critical value.
|
iter |
The number of iterations performed. If iter is smaller than maxit ,
then the algorithm determined because the required level of accuracy was achieved.
|
References
Pötscher, B. M. and Preinerstorfer, D. (2021). Valid Heteroskedasticity Robust Testing. <arXiv:2104.12597>
See Also
davies
, constrOptim
.
Examples
#critical value for the classical (uncorrected) F-test in a location model
#with unrestricted heteroskedasticity
#it is known that (in this very special case) the conventional critical value
#C <- qt(.975, df = 9)^2
#is size-controlling (thus the resulting size should be 5% (approximately))
R <- matrix(1, nrow = 1)
X <- matrix(rep(1, length = 10), nrow = 10, ncol = 1)
hcmethod <- -1
restr.cov <- FALSE
Mp <- 1000
M1 <- 5
M2 <- 1
#here, the parameters are chosen such that the run-time is low
#to guarantee a high accuracy level in the computation,
#Mp, M1 and M2 should be chosen much higher
critical.value(alpha = .05, R, X, hcmethod, restr.cov, Mp, M1, M2)
[Package
hrt version 1.0.1
Index]