fix: clear errors instead of crashes in analyses, stats and utils

[Ramdam17]

What this does

Eight small defects found by the October audit, all of the same kind: a call that crashed obscurely or reported the wrong cause now says what is wrong. No call that worked before returns a different value.

hypyp/analyses.py

• compute_sync rewrote every ValueError as Metric type "..." not supported, so optimization='bogus' was reported as "plv not supported". Only an unknown metric name gets that message now; any other error keeps its own (pair_connectivity cannot forward optimization/priority, and compute_sync masks all compute errors as "metric not supported" #306).
• pair_connectivity called squeeze() on the multitaper signal. With a frequency list and a single epoch, a single channel per participant, or a single frequency such as [10, 11], a dimension disappeared and the next line raised IndexError. The squeeze() is removed; it did nothing when no dimension had length one.

hypyp/utils.py

• normalizing raised UnboundLocalError for a type other than 'Zscore' or 'Logratio'; it raises a ValueError naming the two valid types.
• generate_virtual_epoch failed inside the solver for an odd number of channels; it raises a ValueError, and its docstring example, which used three oscillators, uses four.
• epochs_from_tasks failed with min() iterable argument is empty when the onset event of a task was absent from the recording; the ValueError names the task and the event.
• create_epochs warns when the two participants give different numbers of epochs, or different numbers of recordings. It returns what it returned before.

hypyp/stats.py

• statscluster raised UnboundLocalError for an unknown test; it raises a ValueError listing the valid names.
• metaconn_matrix gains plot=True. The default draws as before; plot=False only computes.

Measured

• 16 new tests, written first; none needs a download. The test of pair_connectivity on a dimension of length one compares the result with a PLV written from its definition.
• Whole suite on macOS arm64, Python 3.12: 325 passed, 42 skipped, 0 failed.
• 112 arrays produced by the touched functions on ordinary inputs (the nine metrics through pair_connectivity with a list and a dictionary of frequencies, compute_nmPLV, normalizing, the cluster wrappers with tail 0 and 1, metaconn_matrix, create_epochs, epochs_from_tasks, generate_virtual_epoch with a fixed seed) are bit-identical between master and this branch, shapes and dtypes included.

Withdrawn after review

Two repairs were in the first version and were taken out, because each made a failing call return numbers that are not established as correct.

• compute_nmPLV has the same squeeze() and the same crash, but the values it returns are the subject of compute_nmPLV applies the n:m exponent to the time axis instead of the channel axis, averages the wrong axis, and calls a deprecated helper #310. It is left as on master.
• statscluster(tail=-1) fails for the usual alpha, because the threshold is positive. Making it run is not a plain repair: the call already succeeds for alpha >= 0.5, the paired test permutes without keeping the pairs, and Stat_obs_plot drops negative values and keeps only the first of several clusters that share a p-value. All of this is left for the work on cluster statistics.

statscluster(test='f multipleway') raises a TypeError on master and still does.

🤖 Generated with Claude Code

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.