bartulem/usv-playpen: v0.11.7

Uniform modeling console output

Every modeling run now prints in one consistent format, across all five task types (onset, params, binomial, multinomial, manifold) and both the univariate and model-selection pipelines. Previously each task printed its own way — some emitted metric-rich per-fold lines, others only a bare > Processing Split N — which made runs hard to compare and hard to read at a glance.

A run is now three parts:

• a run header listing the input files used plus the config that produced them (task, engine, feature/target, split strategy, n_splits, output directory);
• one per-split line in a uniform shape, showing that split's metrics for ACTUAL and NULL, and NULL-MF where the task has a second model-free baseline;
• a two-line end summary: the headline result (ACTUAL vs NULL, or final vs baseline) followed by [timestamp] Success. Results saved to: <full path>.

Model-selection screening, anchor, and forward-step lines are unified to Stage | +feature | metric | decision | detail. The manifold FINAL STATISTICAL SUMMARY table is unchanged.

The formatting lives in shared helpers in modeling_utils.py (format_run_header, format_split_line, format_run_summary, format_selection_step, extract_univariate_headline), each with unit tests, so the format is defined in one place rather than re-derived per pipeline.

This change is console-output only. Fitting, metrics, CV splitting, null generation, acceptance logic, and the contents of every saved pickle are all untouched — no re-run is needed to adopt it.

Bout-parameter engine now fits and scores under one likelihood

The sklearn bout-parameter engine fit a ridge on log(y) — a log-normal assumption — but scored the back-transformed predictions with Gamma deviance (D²). A log-normal model was therefore being graded by a Gamma yardstick, a fit/score likelihood mismatch on the sklearn path.

It is now an L2-penalized GammaRegressor (Gamma GLM, log link), with the penalty chosen by inner-CV Gamma deviance via GridSearchCV over the existing ridge_regression alphas/cv grid. Because the log link targets E[y] directly, both the log transform and the Jensen +σ²/2 back-transform correction are dropped. This matches the pyGAM engine, which was already Gamma-consistent, so the two engines now fit and score under the same likelihood.

The change is applied at all four fit sites — the univariate runner (_run_model_for_feature_sklearn) plus the three model-selection sites (anchor, forward-candidate, final refit). Applying it at only some would have left the sklearn engine fitting Gamma at the univariate stage and log-normal at selection. pyGAM is unchanged.

Re-run note: this changes fitted coefficients and D² scores on the sklearn bout-parameter path, so existing on-disk sklearn params results should be regenerated. Results produced with the pyGAM engine, and all other task types, are unaffected.

Fixes

• Pitch-shifted audio in behavioral videos. frequency_shift_audio_segment() is reached from two different settings blocks, and only one of them was updated when fs_compand_transfer, fs_noise_reduction_std_threshold and fs_sinc_upper_cutoff_hz were moved out of generate_audio_files.py into settings. The analyses block got the three keys; make_behavioral_videos.pitch_shifted_audio_specs did not. Any behavioral-video run with pitch_shifted_audio_bool set therefore died on KeyError: 'fs_compand_transfer'. Both blocks now carry all nine keys the function reads. (fs_sequence_start and fs_sequence_duration remain absent from the video block by design — the caller injects them from the video's own time window.)

  This regression has been present since v0.11.0 and affected every release from v0.11.0 through v0.11.6. If you tried to produce a behavioral video with pitch-shifted audio on any of those versions and hit a KeyError, this is why; the feature works again on v0.11.7 with no change needed on your side beyond upgrading.

Testing

The fs_* regression was invisible to a suite that had tests on both sides of it: every test holding the real settings mocks frequency_shift_audio_segment, and the only test running the real function hand-builds its settings dictionary, so the shipped block and the real reader never met.

A fifth invariant guard (tests/test_settings_contracts.py) now closes that gap without un-mocking anything. For each consumer fed by more than one settings block, it derives the required key set from the consumer's own source and asserts every feeding block supplies it — deriving rather than restating, so the expectation cannot drift out of step with the code. Three contracts are registered: the fs_* pair, the hyperparameters.jax_linear bivariate/multinomial pair (correct today, but read through a single code path with nothing previously enforcing it), and their nested tune_regularization_params sub-blocks. Asymmetries a block is entitled to are declared with a reason, and a second test fails on exemptions that have gone stale.

Documentation

• Modeling.rst is back in step with the shipped modeling_settings.json: the three session-grain manifold-gate keys from v0.11.6 (selection_effect_floor, selection_n_bootstrap, selection_ci_level) are documented, selection_p_val is noted as the BH-FDR q on the manifold target, and a Model-selection note describes the per-session paired-dcor session-bootstrap gate that replaced the old fold-level rule. A stale inner_cv_scoring_metric value (r2_spatial → dcor_xy) is corrected, and every choice parameter now lists its full option set: model_basis_function gains identity, model_target_vocal_type gains state, and model_target_variable and usv_predictor_type now enumerate their exact targets and modes.
• Visualize.rst documented the same incomplete pitch_shifted_audio_specs key set as the settings file, in both the key list and the example JSON; both are corrected.
• CONTRIBUTING.md gains a "Modeling console output" section recording that modeling is the deliberate exception to the no-print rule (it prints run progress directly rather than threading message_output, so ruff T20 fires there and is knowingly left unaddressed), that all such output goes through the shared modeling_utils formatters, and a step-by-step sequence for adding or changing modeling console output — including the requirement that it stay console-only.