janusplot

remains valid under the backward-compat escape.

v0.1.1 Feature 4 — Default fitting engine = bam (with gam escape)

• **New engine = c("bam", "gam") argument**, default "bam". At janusplot's scale (k = 15-25 vars, 600+ fits per call) mgcv::bam's block-Lanczos solve + fREML estimation delivers ~3-10x wall-time speedup vs mgcv::gam without any new dependency (mgcv already exports both).
• **fREML vs REML.** bam defaults to fREML (fast REML); gam defaults to REML. The two methods optimise the same penalty target via different paths — EDFs differ by ~1-3% on identical data. v0.1.1 surfaces this as the one numerical break with v0.1.0, documented prominently above.
• **method argument default is now NULL**, resolved per-engine: "fREML" for bam, "REML" for gam. Users who passed method explicitly in v0.1.0 see no behaviour change.
• **discrete = FALSE (bam-only)** — opt-in to mgcv's covariate-discretisation optimisation. Further ~2-5x speedup at sub-pixel prediction shift cost.
• **nthreads = 1L (bam-only)** — intra-fit threading. Default 1 to avoid oversubscription when combined with parallel = TRUE (which fans out across pair-fits already).
• **engine + method provenance** — both columns now appear in janusplot(..., with_data = TRUE)$data and on every janusplot_data()$pairs[[i]] entry. Useful for paper figures whose methodology section needs to document which backend produced the EDFs they report.
• **bam inherits from gam** — class(bam_fit) is c("bam", "gam", "glm", "lm"), so mgcv::k.check(), predict.gam(), derivative LP-matrix arithmetic, and every shape-metric extractor work without modification. Engine is plumbing, not redesign.
• **vdiffr suite pinned to engine = "gam"** so every legacy visual snapshot continues to validate under the v0.1.0 backward-compat escape. Acts as a regression gate on the engine = "gam" recovery path.

v0.1.1 Feature 3 — Axes rendering modes + figure-to-file output

• **axes** rendering knob with four modes: "original" (default), "standardised", "centred", "rank". Applied per variable from raw data; same transform propagates consistently to (a) raw scatter, (b) spline prediction grid, (c) CI ribbon, and (d) the matrix-border variable label ("mpg (z)", "mpg (centred)", "rank(mpg)").
• **Rendering-only invariant.** The underlying mgcv fits are byte-identical across modes — verified in tests/testthat/test-axes.R via direct column comparison of with_data output across all four modes on a non-linear DGP.
• **At-k coverage.** The new test suite renders every (k, mode) combination across k ∈ {2, 5, 10, 15, 20, 26} and mode ∈ {original, standardised, centred, rank} — 24 panels — and asserts none emit warnings. Border-label suffixing is independently verified at k ∈ {3, 12, 20} by walking patchwork's plot list and matching against the expected suffix pattern.
• **Tier-3 no-op.** At compact tier 3 (n_var >= 25) the cells render only colour fill + shape-class glyph (no curve, no scatter), so axes is a documented no-op there. The border labels still pick up the mode suffix so the user can tell which transform they're looking at.
• **save_as = NULL** — new file-output knob. When set to a path with extension, writes the assembled matrix to disk via [ggplot2::ggsave()]; the device is inferred from the extension. Supported: .png, .pdf, .svg, .jpg / .jpeg, .tif / .tiff, .eps, .ps, .bmp. The function still returns the ggplot — the file is a side-effect.
• **save_width / save_height / save_dpi** — overrides for the auto-resolved square (pmax(6, 0.65 * k_n) inches, 300 dpi for raster). Useful when targeting a fixed-size R Journal figure.

v0.1.1 Feature 2 — Scale-aware compact rendering

• **Progressive content tiers.** New compact argument with values "auto" (default), "always", and "never". Under "auto", each matrix renders at a tier resolved from the pixel-budget ladder:
• Tier 0 (n_var < 12) — v0.1.0 behaviour: spline + CI + scatter
• every annotation.
• Tier 1 (12 <= n_var < 18) — drop raw scatter; keep spline, CI, colour fill, and at most one annotation (k_warn if it was requested).
• Tier 2 (18 <= n_var < 25) — spline + colour fill only.
• Tier 3 (n_var >= 25) — colour mini-tile + shape-class glyph at the cell centre; no spline.
• **Configurable ladder.** compact_threshold = 12L sets where Tier 1 begins; the full ladder shifts with it (t2 = t1 + 6, t3 = t1 + 13). Power users can override the ladder directly via compact_levels = list(t1 = ..., t2 = ..., t3 = ...).
• **Backward-compat escape.** compact = "never" forces Tier 0 on any matrix, reproducing v0.1.0 output regardless of n_var. compact = "always" forces at least Tier 1 even at small n_var (useful for very dense fixed-size renders).
• **Focus filter (companion).** New focus_by argument accepts NA (default — no filter), "asymmetry", "edf", "non_linearity" (defined as edf - 1), or "k_flag". Cells whose chosen metric falls below focus_threshold (default "q90", a quantile string, or a numeric cutoff) are rendered in grey85 at alpha focus_dim_alpha (default 0.25). The matrix shape is preserved; attention drains visually to high-metric cells. This is a **visual filter, not a statistical one** — the underlying fits and the with_data table are unchanged.
• **Rendering-only knob.** Compact tier and focus mask are pure presentation layers. Fits, EDFs, asymmetry indices, shape classifications, k-check diagnostics, and the with_data summary table are byte-identical across compact settings — a regression-tested invariant.

v0.1.1 Feature 1 — Per-cell k-checking (Strategy A always-on + Strategy B opt-in)

• **Diagnostic always on.** Every cell's fit now carries five new diagnostic fields derived from mgcv::k.check(): k_prime, k_index, k_p, k_flag (Wood's trifecta: edf/k' > 0.9 & k-index < 1 & p < 0.05), and k_check_status ("ok", "flagged", "unreliable"). Cells with n_unique(x) < 10 are marked "unreliable" rather than flagged — k.check()'s simulation p-value is meaningless at very low unique-x.
• **Opt-in auto-refit.** New auto_refit_k = FALSE (default) and k_max_iter = 2L arguments on janusplot() and janusplot_data(). With auto_refit_k = TRUE, every flagged cell is refit with a doubling-k loop until either the flag clears, the per-cell unique-x cap is reached, or k_max_iter iterations have passed. Refit trajectory persisted on each cell: k_initial, k_final, k_iterations, k_at_cap.
• **Configurable thresholds.** New k_check_thresholds = list(edf_ratio = 0.9, k_index = 1.0, p = 0.05) argument. Defaults track mgcv::gam.check() and Wood (2017) §5.9.
• **Console summary.** A 3-line cli::cli_inform() summary fires at the end of janusplot() / janusplot_data() whenever at least one cell is flagged: total flagged, chance-expected count under α = 0.05, and a recovery hint pointing at either auto_refit_k = TRUE or k_max_iter. Quiet on clean datasets.
• **Cell annotation.** New "k_warn" entry in the annotations vocabulary on janusplot(). When included, flagged cells render a red ! (ASCII) or ⚠ (Unicode) in the top-left corner. Off by default — opt in with annotations = c("edf", "A", "k_warn").
• **Summary-table extension.** janusplot(..., with_data = TRUE)$data gains 9 new columns: k_prime, k_index, k_p, k_flag, k_check_status, k_initial, k_final, k_iterations, k_at_cap.
• **RNG isolation.** mgcv::k.check() runs its own simulation (default n.rep = 400) for the basis-deficiency p-value. The diagnostic's RNG draw is now isolated via an internal seed-preservation helper, so it does not shift downstream Monte Carlo consumers — derivative_ci = "simultaneous" bands and future.seed = TRUE reproducibility are unaffected.