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.48%. Comparing base (a504eb3) to head (a8b9c5e).

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.33%   90.48%   +1.14%     
==========================================
  Files           6        6              
  Lines        1998     1870     -128     
==========================================
- Hits         1785     1692      -93     
+ Misses        213      178      -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

[mattcieslak]

There's one major change in behavior that this introduces, which is that the pre-filtered dat breaks non-default na.action and removes the na.action attribute on fitted models. Also ModelArray.wrap user functions will now receive filtered rows. I'm not sure how big of a deal either of those changes will be for real users, but I have a hunch it could cause some headaches.

wdyt about keeping all of the other grouping/checking in the pre-fitting context, but keeping the filtering in the per-element runs? I think it would still be a major performance gain.