fix(connectivity): robust normalization; clamp coherence to [0,1]

[edeno]

Summary

• Replace zero-clamp with epsilon-clamp for denominators to prevent numerical instability
• Clip coherence magnitude and imaginary coherence to mathematically valid [0,1] range
• Add comprehensive test suite for bounds verification with edge cases

Changes

• coherency(): Use xp.maximum(norm, xp.finfo().eps) instead of norm[norm == 0] = xp.nan
• coherence_magnitude(): Add xp.clip(magnitude, 0, 1) to ensure valid bounds
• imaginary_coherence(): Add epsilon clamp + [0,1] clipping for numerical stability
• New tests: Verify bounds with random data, edge cases, and zero-power scenarios

Risks & Mitigations

• Low risk: Mathematical constraints enforced, no API changes
• Tests confirm no new failures introduced

Test plan

• 3 new tests pass (bounds checking, edge cases, zero power)
• All existing tests maintain same status
• Coherence values properly bounded in [0,1] range

🤖 Generated with Claude Code

[coveralls]

coverage: 74.35% (+0.1%) from 74.234%
when pulling bb4baca on fix/coherence-clamp-stability
into 6f6c095 on master.

[Copilot]

Pull Request Overview

This PR improves numerical stability in coherency calculations by implementing robust normalization and mathematical bounds enforcement. It replaces zero-clamp operations with epsilon-clamping to prevent division by zero, and clips coherence values to their valid [0,1] range to ensure mathematically correct outputs.

• Replace zero-clamp with epsilon-clamp for denominators to prevent numerical instability
• Add bounds clipping for coherence magnitude and imaginary coherence to [0,1] range
• Include comprehensive test suite to verify proper bounds handling with edge cases

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

File	Description
spectral_connectivity/connectivity.py	Core coherency calculations with epsilon-clamping and bounds clipping
tests/test_coherence_bounds.py	New comprehensive test suite for bounds verification
examples/*.ipynb	Whitespace cleanup removing trailing newlines

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Using xp.finfo(norm.dtype).eps repeatedly could be inefficient. Consider caching this value once since norm.dtype is consistent within the method.

Suggested change

	norm = xp.maximum(norm, xp.finfo(norm.dtype).eps)
	eps = xp.finfo(norm.dtype).eps
	norm = xp.maximum(norm, eps)

[Copilot]

Similar to the coherency method, xp.finfo(denominator.dtype).eps could be cached to avoid repeated computation since the dtype remains constant.

Suggested change

	denominator = xp.maximum(denominator, xp.finfo(denominator.dtype).eps)
	eps = xp.finfo(denominator.dtype).eps
	denominator = xp.maximum(denominator, eps)

[Copilot]

The magic number 1e-15 should be defined as a named constant (e.g., SMALL_VALUE = 1e-15) to improve code readability and maintainability.

[Copilot]

The magic number 1e-16 should be defined as a named constant to improve code readability and maintainability, similar to the 1e-15 value used elsewhere.