Context-Based Refactoring of Element-Wise Analysis Functions

[araikes]

Summary

Refactors the element-wise analysis pipeline to hoist loop-invariant computations (formula parsing, collision checks, cross-scalar source alignment) out of the per-element functions and into precomputed context objects built once before the loop. This eliminates redundant string operations, match() calls, and validation checks in large-scale runs.

Changes

New: analyse-helpers.R — Context builders and shared data assembly

• .build_base_context() — Precomputes scalar name lookups, column-name collision checks, and match()-based source-alignment reorder indices. Supports scalar_subset = NULL (wrap: all scalars) and explicit subset (lm/gam: formula-referenced scalars only).
• .build_lm_context() — Extends base context with all.vars() formula parsing, LHS/RHS variable detection, and scalar predictor identification.
• .build_gam_context() — Extends lm context with cached mgcv::interpret.gam() breakdown.
• .build_wrap_context() — Calls base context in "attach all scalars" mode.
• .assemble_element_data() — Shared per-element helper that reads scalar rows using precomputed reorder indices, builds intersection validity masks, applies subject threshold, and returns the filtered data.frame. Replaces duplicated logic across all three analyseOneElement.* functions.

Modified: ModelArray_Constructor.R — Per-element functions

• analyseOneElement.lm — Accepts optional ctx parameter. When provided, delegates data assembly to .assemble_element_data() and skips all invariant work. Falls back to inline computation when ctx = NULL (backward compatible for direct calls/debugging).
• analyseOneElement.gam — Same ctx/fallback pattern. Preserves (Intercept) → Intercept rename and s(age) → s_age smooth term normalization in the statistics extraction section.
• analyseOneElement.wrap — Same ctx/fallback pattern. Coercion section now properly handles: multi-row data.frame errors, unnamed atomic/list auto-naming (v1, v2, ...), and unsupported return types with informative error messages.

Modified: analyse.R — Top-level dispatchers

• ModelArray.lm() — Builds ctx once via .build_lm_context(), passes through .find_initiator_element() and .parallel_dispatch().
• ModelArray.gam() — Builds ctx once via .build_gam_context(), uses cached gam_formula_breakdown for checker_gam_formula(). Reduced model contexts for changed.rsq are built separately.
• ModelArray.wrap() — Builds ctx once via .build_wrap_context(). Restored missing write_scalar_column_names length validation.

Minor fixes

• stats::setNames() qualified to avoid R CMD check NOTE.
• utils::globalVariables(".") added to suppress magrittr . NOTE.
• subset(select = -c(...)) replaced with bracket-based column removal to eliminate bare-name NOTEs in ModelArray.gam().

Tests: test-analyse_context.R (new)

Organized in five sections following the context hierarchy:

1. Context builder unit tests (base, lm, gam, wrap)
2. .assemble_element_data() — validity masking, threshold, cross-scalar reorder, intersection masks
3. Per-element ctx vs. legacy path equivalence (lm, gam, wrap) — verifies identical output
4. .find_initiator_element() — success and all-elements-fail cases
5. Top-level integration with real HDF5 data (GAM and wrap)

Tests: test-ModelArray_low_hanging_coverage.R (updated)

• Updated expect_error regex patterns to match refactored error messages for unsupported return types and multi-row data.frame validation.

Not Changed

• No changes to HDF5 I/O, streaming writers, p-value correction logic, mergeModelArrays, or S4 class/accessor definitions.
• analyseOneElement.* function signatures remain backward compatible — all existing direct calls work without modification via the ctx = NULL fallback.
• No changes to helper-expected_values.R or the expected value generation logic.

Closes #127

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.76299% with 30 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (a46d78a) to head (aeab037).

Files with missing lines	Patch %	Lines
R/ModelArray_Constructor.R	91.07%	25 Missing ⚠️
R/analyse.R	95.41%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #131      +/-   ##
==========================================
+ Coverage   89.10%   90.24%   +1.14%     
==========================================
  Files           6        6              
  Lines        1974     1846     -128     
==========================================
- Hits         1759     1666      -93     
+ Misses        215      180      -35     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[araikes]

@mattcieslak I'm ok if this waits until a later release but took a shot at reducing some of the redundancy