Add glm_map object class: scikit-learn-style mass-univariate GLM estimator

[torwager]

Summary

Adds a new object class glm_map — a scikit-learn-style estimator for mass-univariate GLM / multiple regression on neuroimaging data. One object bundles:

1. Design specification — wraps an fmri_glm_design_matrix in .design (1st-level / event mode) or holds a direct .X matrix (2nd-level / group mode), plus contrasts.
2. Fitted result maps — betas, t, contrast estimates, and contrast t as statistic_image objects, plus sigma, dfe, residuals.
3. Design diagnostics — VIF, contrast VIF (cVIF), leverage, condition number, rank, and a redundant/near-collinear column report.

glm_map is a standalone container (composition, not an image_vector subclass); fmri_data.regress remains the compute engine. Several attributes (X, TR, onsets, durations, regressor_names, num_*, is_fitted) are true MATLAB Dependent properties that read through to the wrapped design, so there is a single source of truth.

Workflow

% 2nd-level / group (direct design)
g = glm_map('X', X, 'level', 2, 'regressor_names', {'intercept' 'cov'});
g = add_contrasts(g, [0 1], {'cov_effect'});
g = fit(g, fmri_data_obj);          % wraps fmri_data.regress
diagnostics(g); table(g, 'contrast'); montage(g, 'contrast_t');

% 1st-level / event design
g = glm_map(fmri_glm_design_matrix(TR, 'onsets', ons, 'condition_names', names));
g = build_design(g);                % onsets -> X via basis convolution
g = fit(g, timeseries_obj);

% Import an SPM12/SPM25 first-level model
g = import_SPM(glm_map, '/path/SPM.mat');

Commits

• Scaffold: classdef, stored + Dependent properties, constructor, disp; implemented diagnostics, add_contrasts, threshold, montage, table, plot_design, summary, check_properties, private select_map.
• fit: orchestration over fmri_data.regress (robust/AR/threshold/contrasts/names), unpacks outputs into the result maps, runs full diagnostics; AR gated on is_timeseries. Plus multi-image display resolution.
• build_design: event/1st-level design via fmri_glm_design_matrix.build; hardened Dependent accessors against the pre-build 0×0 xX struct.
• import_SPM: SPM12/SPM25 first-level import (struct / SPM.mat path / directory), optional beta loading.
• Docs: glm_map added to CLAUDE.md class list and @image_vector see-also.

Testing

All methods were exercised live in MATLAB (static analysis clean):

• Direct/group fit on load_image_set('emotionreg') → dfe=28, betas [35676×2], diagnostics populated, atlas-labeled table output.
• Event-mode: glm_map(fmri_glm_design_matrix) → build_design → X [200×19] from onsets → fit.
• SPM import: synthetic SPM struct → onsets/condition-names/regressor-names read through → fit → dfe = nscan − nregressors.

Notes: fit, build_design, and import_SPM are fully implemented. Known rough edges are inherited from downstream code (not glm_map): statistic_image.threshold warns on multi-image cluster-extent thresholding, and region/table errors when zero regions survive a threshold.

🤖 Generated with Claude Code