Support unequal-length samples in stochastic dominance and nns_norm

[OVVO-Financial]

Summary

This PR extends stochastic dominance functions (fsd, ssd, tsd, and their *_uni wrappers) to support samples of unequal length, and enhances nns_norm to accept sequence inputs (lists/tuples of vectors) in addition to matrices.

Key Changes

Stochastic Dominance (src/nns/stochastic_dominance.py)

• Unequal-length sample support: Pairwise dominance tests now evaluate each sample's LPM/CDF curve on a merged threshold grid (the union of both samples' sorted values), matching R's NNS.FSD/NNS.SSD/NNS.TSD behavior
• Removed the length-equality constraint from _dominates_uni that previously raised ValueError
• Updated docstrings to clarify that x and y may differ in length
• Extended *_uni wrappers to support unequal lengths with the same merged-grid semantics (an intentional extension beyond R's C++ .uni routines which assume equal lengths)

NNS Norm (src/nns/norm.py)

• Dual input convention support: nns_norm now accepts either:
  • A 2-D matrix (existing behavior)
  • A sequence (list/tuple) of 1-D vectors, matching R's list input convention
• Smart path selection:
  • Equal-length vectors are column-stacked and normalized through the matrix path, returning a 2-D array (mirroring R's mapply simplification)
  • Unequal-length vectors force linear=True (as R does, since dependence-based scale factors require aligned columns) and return a list of scaled arrays
• Added _as_vector helper for input validation with clear error messages
• Added _norm_unequal_series helper implementing linear scaling for unequal-length sequences

Tests (tests/invariants/)

• test_stochastic_dominance.py:

  • Added _r_sd_reference helper transcribing R's decision rule for validation
  • New test test_unequal_length_shifted_samples_dominate verifying dominance with different sample sizes
  • New test test_unequal_length_antisymmetry confirming antisymmetry property holds for unequal lengths
  • New test test_mtcars_transmission_groups_match_r validating against real R dataset results
  • Parametrized test test_unequal_length_matches_r_decision_rule comparing against R's reference implementation across multiple random seeds and dominance degrees

• test_norm.py:

  • New test test_equal_length_sequence_matches_matrix_path verifying sequence and matrix paths produce identical results
  • New test test_unequal_length_sequence_forces_linear_scaling confirming linear scaling behavior and forced linear=True
  • New test test_zero_sum_length_differences_detected_as_unequal edge case for lengths with zero-sum pairwise differences
  • New test test_sequence_input_validation covering error cases (empty sequence, non-1D arrays, non-finite values)

Documentation

• Updated API reference and conventions documentation to clarify unequal-length support and dual input conventions
• Updated API status to reflect the extended capabilities

Implementation Details

• The merged-grid approach for unequal-length dominance is mathematically equivalent to R's implementation: LPM(degree, sort(c(x, y)), sample) per sample
• Linear scaling for unequal-length sequences uses a ratio grid of means to compute uniform scale factors, ensuring all scaled means equal the grand mean of input means
• Input validation for sequence paths provides detailed error messages indicating which element failed and why

https://claude.ai/code/session_01JMQ9tSZyAMwerv7BdY6E5w