Issue A3: API Paper Cut Fix — Improve Error Messages & Defaults

[Ramdam17]

Description:

Identify and fix one "paper cut" in the HyPyP API — small annoyances that frustrate users.

Context:
Paper cuts are minor issues that individually seem small but collectively degrade user experience. Examples: unclear error messages, confusing defaults, inconsistent naming.

Candidate paper cuts to investigate:

1. Unclear error messages

   • Which functions throw cryptic errors?
   • What information would help users debug?

2. Confusing defaults

   • Are default parameters sensible for common use cases?
   • Are defaults documented?

3. Inconsistent naming

   • compute_sync vs compute_freq_bands — consistent verbs?
   • Parameter names consistent across functions?

4. Missing input validation

   • What happens with wrong input shapes?
   • Are errors caught early with helpful messages?

Tasks:

• Use HyPyP for 30 minutes, note every annoyance
• Review GitHub issues for user complaints
• Pick ONE paper cut to fix
• Implement fix with tests
• Update docstrings if needed

Acceptance Criteria:

• One paper cut identified and documented
• Fix implemented with clear commit message
• Unit test for the fix
• Before/after example in PR description

Example fix:

# Before: cryptic error
def compute_sync(data, metric):
    result = _compute(data)  # Crashes deep in code with IndexError

# After: helpful error
def compute_sync(data, metric):
    if len(data) != 2:
        raise ValueError(
            f"Expected data for 2 participants, got {len(data)}. "
            "Data should be a list of two arrays: [participant1, participant2]"
        )
    result = _compute(data)

---