feat(identification): max-share frequency-band identification

[thomaspinder]

Summary

New MaxShare identification scheme: per posterior draw, find the structural shock explaining the largest share of a target variable's variance over a user-selected frequency band, returned through the standard IdentifiedVAR pipeline.

• Math: the band objective M = ∫_B (C_i(e^{-iω})L)*(C_i(e^{-iω})L) dω is Hermitian PSD; for real rotations the maximiser is the top eigenvector of Re(M) — exact, not an approximation (the two-sided band integral is 2·Re(M)). Implemented via the factorisation M = Lᵀ Re(K) L where the frequency accumulator K depends only on the posterior coefficients — computed once and cached, so per-L work (including the stochastic-volatility per-period path) is a cheap batched eigendecomposition. Row extraction uses the plain-transpose solve Fᵀx = eᵢ (the subtlest point — independently re-derived and numerically confirmed by the reviewer).
• User-facing convention: band=(low, high) in periods of the sampling interval (business cycle = (6, 32) quarters; high=inf reaches the zero-frequency limit for low-frequency climate bands, safe under the midpoint quadrature which never evaluates ω=0). Nyquist-validated.
• Partial identification done properly: the single identified column (sign-normalised to a positive target impact) is completed to a full rotation via a Householder reflection; remaining shocks are labelled unidentified_*, flowing through the existing FEVD masking and historical-decomposition remainder collapse unchanged.
• Failure separation (following the feat(identification): long-run (Blanchard-Quah) structural restrictions #183 convention): numerically singular transfer functions at band frequencies are screened by condition number and NaN'd (or raise, via on_undefined); explosive draws warn-and-keep (the factorisation is exact; only the variance interpretation weakens). Diagnostics — achieved share quantiles, top-2 eigenvalue-ratio (weak-identification indicator, warned at >0.9), singular/explosive counts — ride shock_matrix().attrs and a public max_share_diagnostics().
• Includes the same NaN-preserving FEVD _shares fix as PR feat(identification): long-run (Blanchard-Quah) structural restrictions #183 (copied byte-verbatim so the branches auto-merge; reviewer confirmed byte-equality). Docs: explanation section with labelled equations, a how-to with business-cycle and climate examples plus an explicit "variance dominance is not causal identification" admonition, reference entry, CONTEXT.md term, three bib entries.

Closes #145

Review

Planned by a Fable-tier planning agent that verified the math numerically before design (exact analytic recovery; eigen-solution beating a 1024-point rotation grid; Parseval to 5e-16). Independently reviewed with the row-extraction identity and K-accumulator re-derived from scratch and validated on a VAR(2) against an 8193-point trapezoid reference with explicit inversion. Two mechanical P2s fixed in a follow-up commit — including new VAR(2) tests whose necessity was mutation-verified: a reversed lag-order bug invisible to the entire VAR(1) suite fails exactly the three new tests.

Tests

+50 tests: exact analytic recovery on a single-driver DGP (share = 1.0, impact column recovered to machine precision, deliberately non-triangular so the test discriminates from Cholesky); brute-force optimality against an independent quadrature and a 200k-direction sphere sweep; Parseval/FEVD flow-through (frequency-domain share equals time-domain FEVD share to 1e-16); VAR(2) multi-lag pins; singular/explosive/weak-identification screens; full pipeline composition (IRF/FEVD/HD with unidentified_* handling); NaN-draw FEVD preservation.

ruff / ty / fast suite: all green (577 passed, 29 deselected). New docs content renders clean (the only docs-CI warnings are pre-existing stale stubs from other branches' builds, identical on a clean tree).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Egjd7ToFeb9TQqFnfRQZxV

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.18310% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.1%. Comparing base (866ca8f) to head (7cac559).

Files with missing lines	Patch %	Lines
src/impulso/identification.py	96.7%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@          Coverage Diff           @@
##            main    #200    +/-   ##
======================================
  Coverage   95.0%   95.1%            
======================================
  Files         45      45            
  Lines       3099    3240   +141     
  Branches     380     397    +17     
======================================
+ Hits        2945    3082   +137     
- Misses       111     113     +2     
- Partials      43      45     +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.