Spattern {SOAs}

functions to evaluate stratification properties of (O)SOAs and GSOAs

Description

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

Usage

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)

Arguments

D

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.

s

the prime or prime power according to which the array is checked

maxwt

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)

maxdim

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

verbose

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

pat

an object of class Spattern

dimlim

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

wtlim

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

el

the exponent so that the number of levels of the array is s^el (if s is not NULL)

t

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.

Details

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.

Value

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

References

For full detail, see SOAs-package.

Groemping (2023a)
Groemping (2023b)
He and Tang (2013)
Shi and Tang (2020)
Tian and Xu (2022)

Examples

nullcase <- matrix(0:7, nrow=8, ncol=4)
soacheck2D(nullcase, s=2)
soacheck3D(nullcase, s=2)
Spattern(nullcase, s=2)
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))
  ## comparison to maxdim=2 indicates that
  ## the contribution to S_4 from dimensions
  ## larger than 2 is 1
## postprocessing Spat
dim_wt_tab(Spat)

## 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)
## 3D check
soacheck3D(D, s=2, t=4)
## using Spattern (much faster for many columns)
  ## does not have strength 4
  Spattern(D, s=2)
  ## but complies with strength 4 for dim up to 3
  Spattern(D, s=2, maxwt=4, maxdim=3)
  ## inspect more detail
  Spat <- (Spattern(D, s = 2, maxwt=5))
  dim_wt_tab(Spat)