Skip to content

GrangerCausalityResult reuses median()/hdi() names with incompatible return contracts #294

Description

@thomaspinder

Context

Found during the 2026-08-05 architecture review (kept out of the arch/* stack per the PR review policy: a public-API rename requiring design discussion).

Problem

The VARResultBase family defines median() -> pd.DataFrame and hdi(prob) -> HDIResult. GrangerCausalityResult — which does not inherit from it — reuses the same method names with incompatible contracts: median() -> float and hdi() -> tuple[float, float] over the strength norm ‖b‖. Two result families wear one vocabulary with different meanings; a user moving between an IRF result and a Granger result gets silently different shapes from identically-named methods.

Suggested approach

A deliberate naming pass before v0.1 (breaking allowed pre-v0.1):

  • Option A: rename the Granger methods to say what they summarise, e.g. strength_median() / strength_hdi(), keeping summary() as the tabular surface.
  • Option B: make the Granger methods shape-compatible with the family contract (DataFrame / HDIResult over the per-lag posteriors) and expose the norm summaries under new names.

Either way the Granger how-to page and ADR-0010's documented p_rope caveats need a matching pass.

Affected files

  • src/impulso/results.py (GrangerCausalityResult)
  • src/impulso/_granger.py (construction)
  • tests/test_granger.py
  • docs: Granger how-to / tutorial pages

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions