factorH: functions reference

Function reference

This document collects call patterns and options for each public function. All formulas follow response ~ A + B (+ C ...) with a numeric response and factor predictors.

srh.kway.full()

Purpose: one-call pipeline for rank-based ANOVA, descriptive statistics, post hocs, and simple effects.
Syntax: srh.kway.full(y ~ A + B (+ C ...), data, max_levels = 30, type = 2, scope = c("within", "global"))

• Automatically chooses the ANOVA engine:
  • 1 factor: srh.kway()
  • 2 factors with type = 2: srh.effsize()
  • 2 factors with type = 3: srh.kway()
  • 3+ factors: srh.kway()
• Returns a list with the following components:
  • anova
  • summary
  • posthoc_cells
  • posthoc_simple
  • meta
• Placeholders:
  • "[not applicable]" when a component does not apply (e.g., simple effects for a one-factor design),
  • "[failed] ..." when a sub-step fails but the overall pipeline continues.

Example:

res <- srh.kway.full(liking ~ gender + condition + age_cat, data = mimicry)
names(res)
res$anova[1:3]
head(res$summary)
names(res$posthoc_cells)
names(res$posthoc_simple)
res$meta

Notes:

• Predictors are coerced to factors internally; each factor must have between 2 and max_levels levels.
• Rows with missing values in variables used in the formula are removed using complete-case filtering.
• type must be either 2 or 3.
• scope controls Bonferroni adjustment in posthoc_simple; the default is "within", which is passed down to srh.simple.posthocs() and srh.simple.posthoc().
• For one-factor designs, type is accepted for interface consistency, but it has no practical effect on the result.
• For two-factor designs, type = 2 keeps the SRH-style pipeline via srh.effsize(), whereas type = 3 routes the analysis through srh.kway() to follow the logic of Type III sums of squares.
• For designs with 3 or more factors, the ANOVA step is handled by srh.kway() using the requested type.
• For incomplete or sparse factorial plans, the analysis may still run; design-related warnings are stored in res$meta$warnings.

write.srh.kway.full.tsv()

Purpose: export the srh.kway.full() result into a single TSV file for fast formatting.
Syntax: write.srh.kway.full.tsv(obj, file = "srh_kway_full.tsv", sep = "\t", na = "", dec = ".")

• dec = "." or "," controls the decimal mark.
• Numeric fields are written without scientific notation.
• Pretty-printed character tables (e.g., from post hocs) are normalized so that dec = "," also affects numbers embedded in strings.
• The META section exports n, levels, scope, design diagnostics, warnings, and the original call when available.

Example:

f <- file.path(tempdir(), "result.tsv")
write.srh.kway.full.tsv(res, file = f, dec = ",")
file.exists(f)

srh.kway()

Purpose: general k-way SRH-style ANOVA on ranks, tie-corrected p-values, and rank-based effect sizes.
Syntax: srh.kway(y ~ A + B (+ C ...), data, clamp0 = TRUE, force_factors = TRUE, type = 2, ...)

• Reports: Effect, Df, Sum Sq, H, Hadj (tie correction), p.chisq, k, n, eta2H, eps2H.
• eta2H and eps2H are computed from unadjusted H (classical SRH practice).
• force_factors = TRUE coerces predictors to factor (recommended).
• type controls sums of squares. Default type = 2 (Type II SS). Set type = 3 for Type III SS (internally uses sum-to-zero contrasts; no global options are changed).

Example:

k3 <- srh.kway(liking ~ gender + condition + age_cat, data = mimicry)
k3

One-factor check (KW-like):

k1 <- srh.kway(liking ~ condition, data = mimicry)
k1

Two-factor Type III SS:

k2_ss3 <- srh.kway(liking ~ gender + condition, data = mimicry, type = 3)
k2_ss3

srh.effsize()

Purpose: 2-factor SRH table with effect sizes from H.
Syntax: srh.effsize(y ~ A + B, data, clamp0 = TRUE, ...)

• Same columns as above but tailored to the 2-factor SRH pipeline.
• clamp0 = TRUE clamps small negatives to 0 for effect sizes.
• This is the default 2-factor engine used by srh.kway.full(..., type = 2).

Example:

e2 <- srh.effsize(liking ~ gender + condition, data = mimicry)
e2

nonpar.datatable()

Purpose: compact descriptive tables (APA-style), with global mean ranks, medians, quartiles, and IQR.
Syntax: nonpar.datatable(y ~ A + B (+ C ...), data, force_factors = TRUE)

• Returns rows for all main effects and all interaction cells constructed from the RHS.
• Mean ranks are computed on global ranks (all observations ranked together), which matches how omnibus rank-based factorial effects are formed.

Example:

dt <- nonpar.datatable(liking ~ gender + condition, data = mimicry)
head(dt)

srh.posthoc()

Purpose: Dunn-Bonferroni pairwise comparison matrix for one specified effect.
Syntax: srh.posthoc(y ~ A (+ B + ...), data, method = "bonferroni", digits = 3, triangular = c("lower","upper","full"), numeric = FALSE, force_factors = TRUE, sep = ".")

• Builds a single grouping variable (cells) from the RHS factors and runs FSA::dunnTest().
• Returns a list of three matrices (as data frames): Z, P.unadj, P.adj.
• triangular = "lower" (default) shows only the lower triangle; diagonal and upper triangle are masked.
• numeric = FALSE returns pretty-printed character tables; set TRUE to get numeric tables.

Example:

ph <- srh.posthoc(liking ~ condition, data = mimicry)

srh.posthocs()

Purpose: Dunn-Bonferroni pairwise matrices for all effects (main effects and interactions).
Syntax: srh.posthocs(y ~ A + B (+ C ...), data, ...)

• Iterates srh.posthoc() over: A, B, C, A:B, A:C, B:C, A:B:C, …
• Returns a named list: names are "A", "B", "A:B", etc.; each value is a P.adj matrix.

Example:

phs <- srh.posthocs(liking ~ gender + condition + age_cat, data = mimicry)
names(phs)
phs[["gender:condition"]][1:5, 1:5]

srh.simple.posthoc()

Purpose: Simple-effects post hocs (pairwise comparisons within levels of conditioning factors).
Syntax: srh.simple.posthoc(y ~ A + B (+ C ...), data, compare = NULL, scope = c("within","global"), digits = 3)

• compare selects the target factor for pairwise comparisons (default: the first RHS factor).
• Scope:
  • "within" (default): Bonferroni within each by-table (SPSS-like),
  • "global": one Bonferroni correction across all tests from all by-tables combined.
• Returns a data frame with conditioning columns (BY), Comparison, Z, P.unadj, P.adj, m.tests, adj.note. An "adjustment" attribute describes the correction.

Example:

simp <- srh.simple.posthoc(
  liking ~ gender + condition + age_cat,
  data = mimicry,
  compare = "gender",
  scope = "within"
)
head(simp)

srh.simple.posthocs()

Purpose: enumerate all simple-effect configurations for a given design.
Syntax: srh.simple.posthocs(y ~ A + B (+ C ...), data, scope = c("within", "global"))

• For each target factor and each non-empty combination of the remaining factors as BY, runs srh.simple.posthoc(..., compare = target, scope = scope).
• Default is scope = "within", which applies Bonferroni adjustment within each simple-effects table.
• Set scope = "global" to apply one Bonferroni adjustment across all pairwise tests within each simple-effects table.
• Returns a named list, with names like COMPARE(gender) | BY(condition x age_cat).

Example:

sps <- srh.simple.posthocs(liking ~ gender + condition + age_cat, data = mimicry)
head(names(sps), 6)

Global-adjustment variant:

sps_g <- srh.simple.posthocs(
  liking ~ gender + condition + age_cat,
  data = mimicry,
  scope = "global"
)
head(names(sps_g), 6)

as_jamovi_srh_full()

Purpose: normalize srh.kway.full() output into a stable Jamovi-ready list structure.
Syntax: as_jamovi_srh_full(x, show_diagnostics = TRUE, show_intercept = FALSE, keep_empty = FALSE, posthoc_cells_view = c("long", "matrix"), plan_diagnostics = NULL)

• Converts the pipeline result into plain R sections and items that can be mapped by a Jamovi backend.
• Normalizes ANOVA, descriptives, post hoc matrices, simple-effects tables, compact diagnostics, optional full plan diagnostics, and meta/info blocks.
• Supports "long" or "matrix" view for post hoc cell comparisons.

Example:

res <- srh.kway.full(liking ~ gender + condition, data = mimicry)
jam <- as_jamovi_srh_full(res)
names(jam)

normality.datatable()

Purpose: Shapiro-Wilk normality tests for the raw response within each subgroup for all factor combinations.
Syntax: normality.datatable(y ~ A + B (+ C ...), data, force_factors = TRUE)

• Returns Effect, factor columns, count, W, p.shapiro (fixed-format to 4 decimals, no scientific notation), and OK/NOT OK (p < 0.05 => NOT OK).

Example:

normality.datatable(liking ~ gender + condition + age_cat, data = mimicry)

residuals.normality.datatable()

Purpose: Shapiro-Wilk tests on global residuals from a classical ANOVA fitted to the selected factors; one test per model.
Syntax: residuals.normality.datatable(y ~ A + B (+ C ...), data, force_factors = TRUE)

• Returns one row per Effect (A, B, A:B, …), with count, W, p.shapiro (4 decimals), OK/NOT OK.
• This function is retained mainly for continuity with older workflows; for stricter ANOVA-style checking, use the cellwise residual variant.

Example:

residuals.normality.datatable(liking ~ gender + condition + age_cat, data = mimicry)

residuals.cellwise.normality.datatable()

Purpose: Shapiro-Wilk tests of residuals from a classical ANOVA model, tested separately within each cell.
Syntax: residuals.cellwise.normality.datatable(y ~ A + B (+ C ...), data, force_factors = TRUE)

• This matches the classical ANOVA assumption of normal errors per cell.
• Returns rows for every cell across all Effects, with count, W, p.shapiro (4 decimals), OK/NOT OK.

Example:

residuals.cellwise.normality.datatable(liking ~ gender + condition + age_cat, data = mimicry)

balance.chisq.datatable()

Purpose: count-balance diagnostics across design factors.
Syntax: balance.chisq.datatable(y ~ A + B (+ C ...), data, force_factors = TRUE)

• For one factor: chi-square goodness-of-fit vs equal proportions.
• For two factors: chi-square test of independence.
• For three or more: log-linear independence model (Poisson; main effects only), assessed via deviance and df.
• Returns Effect, n, ChiSq (4 decimals), df, p.chisq (4 decimals), OK/NOT OK (p < 0.05 => NOT OK).
• The response is ignored; only RHS factors are used to build the tables.

Example:

balance.chisq.datatable(liking ~ gender + condition + age_cat, data = mimicry)

levene.plan.datatable()

Purpose: Levene/Brown-Forsythe test for homogeneity of variances across full-plan cells (highest-order interaction of RHS factors).
Syntax: levene.plan.datatable(y ~ A + B (+ C ...), data, center = "median", force_factors = TRUE)

• This is the primary variance-equality diagnostic for a full factorial plan.
• Returns F, df.num, df.den, p (4 decimals), and OK/NOT OK (p < 0.05 => NOT OK).

Examples:

levene.plan.datatable(liking ~ gender + condition + age_cat, data = mimicry)
levene.plan.datatable(liking ~ gender + condition, data = mimicry, center = "mean")

plan.diagnostics()

Purpose: orchestrates all diagnostics in one call.
Syntax: plan.diagnostics(y ~ A + B (+ C ...), data, force_factors = TRUE)

• Runs raw normality (cellwise on the response), residuals cellwise normality, Levene/Brown-Forsythe for the full plan (median by default), and balance chi-square tests for all factor combinations.
• Prints a concise console summary and returns full tables in a list.

Returned list:

$summary: percent_ok, ok_count, total, overall, plus per-type percentages:
percent_ok_normality_raw, percent_ok_residuals_cellwise, percent_ok_balance_chisq, percent_ok_levene_full_plan.

$results: normality_raw, residuals_cellwise_normality, levene_full_plan, balance_chisq.

Examples:

diag_out <- plan.diagnostics(liking ~ gender + condition + age_cat, data = mimicry)
diag_out$results$normality_raw
diag_out$results$residuals_cellwise_normality
diag_out$results$levene_full_plan
diag_out$results$balance_chisq
diag_out$summary

Formula tips and pitfalls

• Do not write A:B or A*B. Use A + B (+ C ...); the package computes all necessary interaction structures internally.
• The response must be numeric. For Likert data, keep it numeric 1..k.
• Predictors should be factors. If they are not, they will be coerced internally.

Example:

mimicry$gender <- factor(mimicry$gender)
mimicry$condition <- factor(mimicry$condition)

Performance and reproducibility

• The package combines SRH-style logic, rank-based linear-model ANOVA, and Dunn post hocs depending on the function and the selected type.
• P-values use tie correction where appropriate; rank-based effect sizes are derived from unadjusted H (classical SRH practice).
• Outputs are plain data frames and lists, easy to save, normalize, and post-process.

C:0u34e45b057346-reference.R