R/checkStratification.R
Spattern.Rdsoacheck2D and soacheck3D evaluate 2D and 3D projections,
Spattern calculates the stratification pattern by Tian and Xu (2022),
and dim_wt_tab extracts and formats the dim_wt_tab attribute of Spattern.
Spattern(D, s, maxwt = 4, maxdim = NULL, verbose = FALSE, ...)
dim_wt_tab(pat, dimlim = NULL, wtlim = NULL, ...)
soacheck2D(D, s = 3, el = 3, t = 3, verbose = FALSE)
soacheck3D(D, s = 3, el = 3, t = 3, verbose = FALSE)a matrix with factor levels or an object of class SOA or a
data.frame object with numeric columns.
Functions soacheck2D and soacheck3D require levels
that are consecutively numbered (starting with 0 or 1).
Function Spattern also works, if all columns of D
have the same number of unique numeric values; the function will code them using
power contrasts.
the prime or prime power according to which the array is checked
maximum weight to be considered for the pattern (default: 4; see Details);
if the specified limit is larger than maxdim*el,
it is reduced accordingly (where el is such that s^el is the number of levels)
maximum dimension to be considered for the pattern (default: NULL implies that maxdim=min(maxwt, ncol(D));
see also Details);
if the specified limit is larger than m=ncol(D), it is reduced to m
logical; if TRUE, additional information is printed
(for Spattern, status information during run time; for the SOAcheck... functions, confounded pair or triple projections with A2 or A3, respectively, or table of correlations)
currently not used
an object of class Spattern
integer; limits the returned dimension rows to the
rows from 1 up to dimlim; the bottom margin continues to include all
dimensions that were used in calculating pat
integer; limits the returned weight columns to the columns from
1 up to wtlim; the right margin continues to include all weights
that were used in calculating pat
the exponent so that the number of levels of the array is s^el
(if s is not NULL)
the strength for which to look (2, 3, or 4), equal to the sum of the
exponents in the stratification dimensions; for example, soacheck2D considers
sxs 2D projections with t=2,
s^2xs and sxs^2 projections with t=3,
and s^3xs, s^2xs^2 and sxs^3 projections with t=4.
If t=4 and el=2, property gamma (s^3 x s and s x s^3) is obviously
impossible and will not be part of the checks.
Function Spattern returns an object of class Spattern
that is a named vector with attributes:
The attribute call holds the function call
(and thus documents, e.g., limits set on dimension and/or weight).
The attribute dim_wt_tab holds a table of contributions
split out by dimension (rows) and weights (columns), which has class
dim_wt_tab and the further attribute Spattern-class.
Function dim_wt_tab returns the dim_wt_tab attribute of
an object of class Spattern; note that the object contains NA values
for combinations of dimension and weight that cannot occur.
Function dim_wt_tab postprocesses an Spattern object
and produces a table that holds the S pattern entries
separated by the dimension of the contributing effect column group (rows)
and the weight of the effect column micro group (columns). The margin shows row and
column sums (see Details section for caveats).
Function Spattern calculates the stratification pattern or S pattern
as proposed in Tian and Xu (2022) (under the name space-filling pattern);
the details and the implementation in this function are described in
Groemping (2023b); the function uses the full-factorial-based Helmert contrasts.
Position j in the S pattern shows the imbalance when considering s^j
strata. j is also called the (total) weight. j=1 can occur for an
individual column only. j=2 can be obtained either for an
s^2 level version of an individual column or for the crossing of
s^1 level versions of two columns, and so forth.
Obtaining the entire S pattern
can be computationally demanding. The arguments maxwt and
maxdim limit the effort (choose NULL for no limit):maxwt gives an upper limit for the weight j of the previous paragraph;
if NULL, maxwt is set to maxdim*el.maxdim limits the number of columns that are considered in combination.
When using a non-null maxdim, pattern entries for j larger than maxdim can be smaller
than if one would not have limited the dimension. Otherwise, dimensionality is unlimited,
which is equivalent to specifying maxdim as the minimum of maxwt and ncol(D).
Spattern with maxdim=2 and maxwt=t can be used as an alternative
to soacheck2D,
and analogously Spattern with maxdim=2 and maxwt=t can be used as an alternative
to soacheck3D.
An Spattern object
object can be post-processed with function dim_wt_tab. That function splits
the S pattern into contributions from effect column groups of different dimensions,
arranged with a row for each dimension and a column for each weight.
If Spattern was called with maxdim=NULL and
maxwt=NULL, the output object shows the GWLP in the right margin and the
S pattern in the bottom margin. If Spattern was called with relevant restrictions
on dimensions (maxdim, default 4) and/or weights (maxwt, default 4),
sums in the margins can be smaller than they would be for unconstrained dimension and
weights.
Functions soacheck2D and soacheck3D were available before
function Spattern; many of their use cases can now be handled with Spattern
instead. The functions are often fast to yield a FALSE outcome,
but can be very slow to yield a TRUE outcome for larger designs.
The functions inspect 2D and 3D
stratification, respectively. Each column must have s^el levels.
t specifies the degree of balance the functions are asked to look for.
Function soacheck2D,
with el=t=2, looks for strength 2 conditions (s^2 levels, sxs balance),
with el=2, t=3, looks for strength 2+ / 3- conditions (s^2 levels, s^2xs balance),
with el=t=3, looks for strength 2* / 3 conditions (s^3 levels, s^2xs balance).
with el=2, t=4, looks for the enhanced strength 2+ / 3- property alpha (s^2 levels, s^2xs^2 balance).
and with el=3, t=4, looks for strength 3+ / 4 conditions (s^3 levels, s^3xs and s^2xs^2 balance).
Function soacheck3D,
with el=2, t=3, looks for strength 3- conditions (s^2 levels, sxsxs balance),
with el=t=3, looks for strength 3 conditions (s^3 levels, sxsxs balance),
and with el=3, t=4, looks for strength 3+ / 4 conditions (s^3 levels, s^2xsxs balance).
If verbose=TRUE, the functions print the pairs or triples that violate
the projection requirements for 2D or 3D.
For full detail, see SOAs-package.
Groemping (2023a)
Groemping (2023b)
He and Tang (2013)
Shi and Tang (2020)
Tian and Xu (2022)
nullcase <- matrix(0:7, nrow=8, ncol=4)
soacheck2D(nullcase, s=2)
#> [1] FALSE
soacheck3D(nullcase, s=2)
#> [1] FALSE
Spattern(nullcase, s=2)
#> 1 2 3 4
#> 0 6 0 13
#> attr(,"call")
#> Spattern(nullcase, s = 2)
Spattern(nullcase, s=2, maxdim=2)
#> 1 2 3 4
#> 0 6 0 12
#> attr(,"call")
#> Spattern(nullcase, s = 2, maxdim = 2)
## the non-zero entry at position 2 indicates that
## soacheck2D does not comply with t=2
(Spat <- Spattern(nullcase, s=2, maxwt=4))
#> 1 2 3 4
#> 0 6 0 13
#> attr(,"call")
#> Spattern(nullcase, s = 2, maxwt = 4)
## comparison to maxdim=2 indicates that
## the contribution to S_4 from dimensions
## larger than 2 is 1
## postprocessing Spat
dim_wt_tab(Spat)
#> 1 2 3 4 Sum
#> 1 0 0 0 . 0
#> 2 . 6 0 12 18
#> 3 . . 0 0 0
#> 4 . . . 1 1
#> Sum 0 6 0 13 19
## Shi and Tang strength 3+ construction in 7 8-level factors for 32 runs
D <- SOAs_8level(32, optimize=FALSE)
## check for strength 3+ (default el=3 is OK)
## 2D check
soacheck2D(D, s=2, t=4)
#> [1] TRUE
## 3D check
soacheck3D(D, s=2, t=4)
#> [1] TRUE
## using Spattern (much faster for many columns)
## does not have strength 4
Spattern(D, s=2)
#> 1 2 3 4
#> 0 0 0 7
#> attr(,"call")
#> Spattern(D, s = 2)
## but complies with strength 4 for dim up to 3
Spattern(D, s=2, maxwt=4, maxdim=3)
#> 1 2 3 4
#> 0 0 0 0
#> attr(,"call")
#> Spattern(D, s = 2, maxwt = 4, maxdim = 3)
## inspect more detail
Spat <- (Spattern(D, s = 2, maxwt=5))
dim_wt_tab(Spat)
#> 1 2 3 4 5 Sum
#> 1 0 0 0 . . 0
#> 2 . 0 0 0 14 14
#> 3 . . 0 0 56 56
#> 4 . . . 7 0 7
#> 5 . . . . 0 0
#> Sum 0 0 0 7 70 77