# 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 `Effect`s, 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