Generation and Analysis of Confounded and Fractional Factorial Block Designs

Description

Internal package-level roxygen directives used to generate the package 'NAMESPACE' automatically with roxygen2.

Author(s)

Maintainer: Sukanta Dash sukanta.iasri@gmail.com

Authors:

• Vankudoth Kumar kumarvankudoth51@gmail.com

• Med Ram Verma drmrverma@gmail.com

Analyze factorial block-design characteristics

Description

Computes incidence-based, estimability, balance, confounding, discrepancy, and optimality summaries for a factorial block design.

Usage

FactChar(factor_levels, blocks)

Arguments

Details

This function contains several local helper functions for pseudo-inverse calculation, contrast construction, Das-style diagnostics, discrepancy measures, and confounding checks. Those helper functions are scoped locally and are not intended to be documented as separate package-level functions.

Value

An object of class '"lfebd3_analysis"' containing the incidence matrix, C-matrix, design-property flags, confounding summary, discrepancy criteria, optimality diagnostics, and Das-style summaries. Use 'print()' to display the formatted report.

See Also

[build_block_matrix()], [lfbd_analyze()], [lfbd.cf.full()]

Convert a full confounded LFBD data frame into blocks

Description

Extracts block columns from a data frame returned by lfbd.cf.full().

Usage

as_blocks_from_cf_full(design_df)

Arguments

Value

A named list of character vectors, one vector per block.

Convert a run-ordered design into equal-sized blocks

Description

Splits the Treatment column of a run-ordered design data frame into consecutive blocks of a specified size.

Usage

as_blocks_from_runs(design_df, block_size)

Arguments

Value

A named list of character vectors, one vector per block.

Build a treatment-by-block incidence matrix

Description

Creates the incidence matrix for a block design from a list of treatment labels grouped by block.

Usage

build_block_matrix(blocks)

Arguments

Value

A binary matrix with treatments in rows and blocks in columns.

See Also

[convert_to_blocks()], [FactChar()]

Build a model matrix for factorial effects

Description

Generates the treatment-effect model matrix for a factorial design using sum-to-zero contrasts.

Usage

build_effect_matrix(trts, factor_levels)

Arguments

Value

A model matrix with one row per treatment combination.

See Also

[FactChar()]

Build recursive triplets for fractional or confounded reduction

Description

Recursively partitions a design matrix into three components and returns three reduced patterns used in the fractional and confounded selection rules.

Usage

build_triplet(mat, type = c("fractional", "confounded"))

Arguments

Details

For 9-row base cases, the selection rule differs by 'type'. Fractional reduction uses consecutive row groups, whereas confounded reduction uses interleaved row groups. Larger matrices are handled recursively.

Value

A list of three matrices, conventionally interpreted as 'P1', 'P2', and 'P3'.

See Also

[reduce_once()], [reduce_repeated()]

Canonicalize a mod-3 effect vector

Description

Standardizes a nonzero effect vector so that its first nonzero coefficient is equal to '1' in mod-3 arithmetic.

Usage

canonical_effect(v)

Arguments

Value

A canonicalized numeric vector in mod 3.

See Also

[effect_label()], [find_defining_contrasts()]

Convert a generated design object to a block list

Description

Converts either a treatment-run data frame or a block-wise design data frame into a named list of blocks.

Usage

convert_to_blocks(design_df)

Arguments

Value

A named list where each element is a character vector of treatment labels belonging to one block.

See Also

[build_block_matrix()], [FactChar()]

Generate the defining subgroup from a defining-contrast basis

Description

Forms all mod-3 linear combinations of the supplied defining contrasts.

Usage

defining_subgroup(B)

Arguments

Value

A matrix whose rows enumerate the defining subgroup.

See Also

[find_defining_contrasts()], [low_order_aliases_from_subgroup()]

Compute direct aliases from defining contrasts

Description

Combines an effect with each defining contrast, and optionally with multiples of each contrast, to obtain direct aliases.

Usage

direct_aliases_from_dc(v, dc_basis, include_multiples = FALSE)

Arguments

Value

A character vector of unique direct aliases.

See Also

[find_defining_contrasts()], [low_order_aliases_from_subgroup()]

List low-order aliases for an effect

Description

Computes low-order aliases of a target effect using a supplied defining subgroup.

Usage

effect_aliases_low_order(v, subgroup, max_order = 2)

Arguments

Value

A sorted character vector of aliased low-order effects.

See Also

[low_order_aliases_from_subgroup()]

Convert an effect vector to a compact label

Description

Converts a mod-3 effect vector to the string representation used throughout the aliasing and confounding summaries.

Usage

effect_label(v)

Arguments

Value

A character string such as '"I"', '"F11"', or '"F11F22"'.

See Also

[effect_order()], [canonical_effect()]

Compute the order of an effect vector

Description

Counts the number of nonzero coefficients in a mod-3 effect vector.

Usage

effect_order(v)

Arguments

Value

Integer giving the number of active factors in the effect.

See Also

[effect_label()], [canonical_effect()]

Find defining contrasts for a fractional design

Description

Searches the effect space for mod-3 contrasts satisfied by a design matrix and extracts an independent basis of defining contrasts.

Usage

find_defining_contrasts(design_mat, expected_c = NULL)

Arguments

Value

A list with components:

basis

A matrix whose columns form an independent basis of defining contrasts.

labels

Character vector of labels for the defining contrasts.

See Also

[defining_subgroup()], [fractional_confounding_summary()], [lfbd.fr()]

Summarize aliasing and confounding in a fractional LFBD

Description

Produces a low-order summary for main effects and two-factor interactions under the defining subgroup of a fractional 3-level factorial design.

Usage

fractional_confounding_summary(n, dc_basis)

Arguments

Value

A data frame describing each listed effect, its order, low-order aliases, and simple estimability/confounding indicators.

See Also

[find_defining_contrasts()], [lfbd.fr()]

Generate the full ternary construction matrix

Description

Builds the full recursive ternary matrix used as the foundation for generating complete, fractional, and confounded 3-level factorial layouts in this script.

Usage

generate_Tn_full(n)

Arguments

Details

The construction starts from a single-column seed and applies the 3-by-3 recursive expansion rule 'n' times. The returned matrix is transposed so that downstream functions can extract the square design submatrix directly.

Value

A matrix with entries in 0, 1, and 2 representing the full ternary construction after n recursive expansions.

References

Elsawah, A.M. Multiple doubling: a simple effective construction technique for optimal two-level experimental designs. Statistical Papers 62, 2923–2967 (2021). DOI: 10.1007/s00362-020-01221-0

Gupta, S. C. (1983). Some new methods for constructing block designs having orthogonal factorial structure. Journal of the Royal Statistical Society, Series B (Methodological), 45, 297-307.

See Also

[get_Tn_square()], [lfbd()], [lfbd.fr()], [lfbd.cf()]

Examples

generate_Tn_full(1)
dim(generate_Tn_full(2))
get_Tn_square(1)
dim(get_Tn_square(2))
d <- lfbd(2)
d
nrow(d)
d <- lfbd.fr(2, 1)
d
attr(d, "defining_contrasts")
lfbd.cf(2, 1)
dim(lfbd.cf(3, 2))
d <- lfbd.cf.full(2, 1)
d
colnames(d)
d <- lfbd(2)
blk <- convert_to_blocks(d)
blk
d <- lfbd.cf.full(2, 1)
convert_to_blocks(d)
d <- lfbd.cf.full(2, 1)
blk <- convert_to_blocks(d)
build_block_matrix(blk)
X <- build_effect_matrix(NULL, c(3, 3))
dim(X)
head(X)
d <- lfbd.cf.full(2, 1)
blk <- convert_to_blocks(d)
res <- FactChar(c(3, 3), blk)
print(res)
res <- lfbd_analyze(
  type = "lfbd.cf.full",
  factor_levels = c(3, 3),
  n = 2,
  r = 1,
  show_design = FALSE,
  run_analysis = FALSE
)
names(res)

Generate a catalog of effects up to a chosen order

Description

Enumerates main effects and, optionally, two-factor interactions for a symmetric factorial design coded in mod 3.

Usage

generate_effect_catalog(n, max_order = 2)

Arguments

Value

A list with components 'mat', 'labels', and 'orders'.

See Also

[fractional_confounding_summary()]

Extract the square design matrix for a 3-level factorial construction

Description

Computes the square submatrix used as the base design matrix for the LFBD generators.

Usage

get_Tn_square(n)

Arguments

Value

A '3^n x n?' style square matrix derived from the full ternary construction, with the first '3^n' rows retained after transposition.

See Also

[generate_Tn_full()], [lfbd()], [lfbd.fr()], [lfbd.cf()]

Test linear independence modulo 3

Description

Checks whether adding a vector to an existing basis increases its mod-3 rank.

Usage

is_independent_mod3(B, v)

Arguments

Value

Logical value; 'TRUE' if 'v' is independent of the columns of 'B' over mod 3, otherwise 'FALSE'.

See Also

[rank_mod3()], [find_defining_contrasts()]

Generate a complete factorial LFBD

Description

Creates the complete 3-level factorial layout from the ternary design construction and returns treatment labels in run order.

Usage

lfbd(n)

Arguments

Value

A data frame with columns:

Run

Run labels such as '"run1"', '"run2"', ...

Treatment

Treatment combination labels formed by concatenating factor levels coded as '0', '1', and '2'.

See Also

[lfbd.fr()], [lfbd.cf.full()], [lfbd_analyze()]

Generate the principal block for a confounded LFBD

Description

Extracts the principal block of size '3^r' from a complete 3-level factorial design using the recursive confounded selection rule.

Usage

lfbd.cf(n, r)

Arguments

Value

A matrix representing the principal block.

See Also

[lfbd.cf.full()], [reduce_repeated()]

Generate the full confounded factorial design

Description

Builds the complete set of blocks induced by the principal block of a confounded 3-level factorial design.

Usage

lfbd.cf.full(n, r, max_blocks_display = 12)

Arguments

Value

An invisible data frame whose first column identifies units and whose remaining columns correspond to blocks ('blk1', 'blk2', ...).

See Also

[lfbd.cf()], [convert_to_blocks()], [FactChar()]

Generate a fractional 3-level LFBD

Description

Constructs a fractional layout from the complete ternary design by repeated fractional reduction and returns the design together with defining contrasts and a low-order confounding summary.

Usage

lfbd.fr(n, c)

Arguments

Value

An object of class '"lfbd_fr"' containing:

design

A data frame with run labels and treatment labels.

design_matrix

The reduced numeric design matrix.

defining_contrasts

Character vector of defining contrast labels.

confounding_summary

Data frame of main-effect and 2FI summaries.

See Also

[lfbd()], [lfbd.cf()], [lfbd_analyze()]

Examples

d <- lfbd.fr(2, 1)
d$design
d$defining_contrasts

Generate and analyze an LFBD in one call

Description

Wrapper that generates a complete, fractional, or confounded LFBD and then, optionally, analyzes its design characteristics.

Usage

lfbd_analyze(
  type = c("lfbd", "lfbd.fr", "lfbd.cf.full"),
  factor_levels,
  n,
  c = NULL,
  r = NULL,
  block_size = NULL,
  show_design = TRUE,
  run_analysis = TRUE
)

Arguments

Details

This wrapper uses internal helper functions to convert generated designs into block lists and to print the generated design before analysis.

Value

Invisibly returns a list with the selected design type, generated design object, derived block list, and analysis output.

See Also

[lfbd()], [lfbd.fr()], [lfbd.cf.full()], [FactChar()]

Compute low-order aliases from a defining subgroup

Description

Adds a target effect to each subgroup element and retains aliases whose order does not exceed 'max_order'.

Usage

low_order_aliases_from_subgroup(v, subgroup, max_order = 2)

Arguments

Value

A sorted character vector of unique low-order aliases.

See Also

[defining_subgroup()], [fractional_confounding_summary()]

Print an lfebd3 analysis object

Description

Displays the formatted report for an object returned by [FactChar()].

Usage

## S3 method for class 'lfebd3_analysis'
print(x, ...)

Arguments

Value

Invisibly returns 'x'.

Print a generated design

Description

Convenience printer used by lfbd_analyze() to display the generated design object.

Usage

print_generated_design(design_df)

Arguments

Value

Invisibly returns design_df.

Compute matrix rank over the field of integers mod 3

Description

Performs Gaussian elimination modulo 3 to determine the rank of a matrix.

Usage

rank_mod3(M)

Arguments

Value

Integer rank of 'M' computed under mod-3 arithmetic.

See Also

[is_independent_mod3()]

Reduce a design matrix by one factor of three

Description

Applies a single fractional or confounded reduction step to a design matrix by selecting the first recursive pattern returned by [build_triplet()].

Usage

reduce_once(mat, type = c("fractional", "confounded"))

Arguments

Value

A reduced matrix with one-third as many rows as 'mat' when reduction is possible.

See Also

[build_triplet()], [reduce_repeated()]

Repeatedly reduce a design matrix

Description

Applies [reduce_once()] iteratively to obtain a smaller fractional or confounded design.

Usage

reduce_repeated(mat, times, type = c("fractional", "confounded"))

Arguments

Value

A matrix obtained after 'times' successive reductions.

See Also

[reduce_once()], [lfbd.fr()], [lfbd.cf()]