[plotting] Allow user to specify type of posterior data visualisation

[AllenDowney]

Summary

This draft PR extends the plotting capabilities of CausalPy to support multiple visualization types for posterior data. The purpose of this draft PR is to discuss the API design and approach, not to finalize implementation or testing.

Currently, CausalPy only supports CI ribbon visualizations using Highest Density Intervals (HDI). This PR adds:

• Support for Equal-Tailed Intervals (ETI) in addition to HDI
• Support for histogram visualizations
• Support for spaghetti plot visualizations (individual posterior sample trajectories)

The API design aligns with ArviZ's naming conventions (ci_prob, ci_kind) while maintaining backward compatibility with existing code.

Fixes #671

Changes

• Extended plot_xY() function (causalpy/plot_utils.py):

  • Added kind parameter: "ribbon", "histogram", or "spaghetti" (default: "ribbon")
  • Added ci_kind parameter: "hdi" or "eti" (default: "hdi" to match current behavior)
  • Added ci_prob parameter (default: 0.94 to match current behavior)
  • Added num_samples parameter for spaghetti plots (default: 50)
  • Maintained backward compatibility with hdi_prob parameter
  • Implemented three visualization types:
    • Ribbon: HDI/ETI intervals using ArviZ functions
    • Histogram: Marginal histograms at key time points (basic implementation -- will be extended after API review)
    • Spaghetti: Random posterior sample trajectories with mean overlay

• Updated BaseExperiment.plot() method (causalpy/experiments/base.py):

  • Added new parameters to method signature
  • Parameters are passed through to _bayesian_plot() and _ols_plot() methods
  • Maintains backward compatibility (all parameters optional with defaults)

Testing

• Manual testing completed in marimo notebook (causalpy_test.py) demonstrating all visualization types
• All visualization types verified to render correctly
• Pre-commit checks pass (linting, formatting, type checking)
• Note: Unit and integration tests are deferred until after API review and feedback

API Design Rationale

1. kind parameter: Uses familiar naming convention from seaborn/pandas
2. ci_prob and ci_kind naming: Aligns with ArviZ's naming conventions for ecosystem consistency
3. Default values: Match current behavior (0.94, "hdi") to maintain backward compatibility
4. Backward compatibility: Existing code using hdi_prob continues to work unchanged

Open Questions for Reviewers

1. Any comments or suggestions on the proposed API?
2. Should we proceed with updating all experiment classes (_bayesian_plot() methods) to explicitly accept and pass through these parameters, or is passing via **kwargs sufficient?
3. Are the default values (0.94, "hdi") appropriate, or should we consider ArviZ's new defaults (0.89, "eti")?

Checklist

• Pre-commit checks pass
• Code follows project conventions
• All tests pass (deferred until after API review)
• Documentation updated (deferred until after API review)
• Example notebooks created (deferred until after API review)

---

📚 Documentation preview 📚: https://causalpy--680.org.readthedocs.build/en/680/

[drbenvincent]

Thanks @AllenDowney ! Hoping to look at this very soon. Just flagging up that there might be some conflicts to resolve if #643 gets merged first. That one allows the user to decide if they are looking at things related to the posterior expectation or the posterior predictive. So these PR's are nicely complementary, but it's possible there could be some code overlap/conflicts.