Deprecate rhat() and neff_ratio() in favor of extract_rhat()/extract_neff_ratio()

[utkarshpawade]

Fixes #295

Deprecates rhat() and neff_ratio() in favor of extract_rhat() and extract_neff_ratio(). The old names clashed with same-named functions in the posterior package, which actually compute R-hat / ESS, whereas bayesplot's versions only extract already-computed values from a fitted model. The name collision masked posterior::rhat() when both packages were loaded and confused users about what the functions were doing under the hood.

Per the discussion in #295, rename + deprecate was the only viable path, posterior's functions aren't drop-in replacements, so wrapping or removal wasn't an option.

changes:

• New generics extract_rhat() / extract_neff_ratio() with the existing stanfit, stanreg, and CmdStanMCMC methods renamed to match.
• rhat() and neff_ratio() are now thin deprecated wrappers that emit lifecycle::deprecate_warn("1.16.0", ...) and forward to the new generics. Behavior is otherwise unchanged, so existing user code keeps working with a warning.
• Docs, examples, and the Visual MCMC diagnostics vignette updated to use the new names; added a short note about the rename.
• NAMESPACE and man/*.Rd regenerated via roxygen.
• The internal rhat / neff_ratio S3 classes (used by mcmc_rhat_data(), [.rhat, diagnostic_factor.rhat, etc.) are intentionally left alone, they describe data objects, not the deprecated functions.

[Copilot]

Pull request overview

This PR resolves #295 by renaming bayesplot’s R-hat and ESS extractor APIs to avoid masking similarly named computational functions in the posterior package, while keeping the old names available via deprecation warnings.

Changes:

• Added new S3 generics extract_rhat() / extract_neff_ratio() and renamed existing methods to extract_*.<class>.
• Converted rhat() / neff_ratio() into deprecated wrappers that warn via lifecycle::deprecate_warn() and forward to the new generics.
• Updated docs, vignette examples, NAMESPACE, and tests to use the new names and to verify deprecation warnings.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
R/bayesplot-extractors.R	Introduces extract_* generics/methods and makes rhat()/neff_ratio() deprecated forwarding wrappers.
R/mcmc-diagnostics.R	Updates roxygen references to point users to the new extractor names.
R/mcmc-intervals.R	Updates roxygen references/examples to use extract_rhat().
tests/testthat/test-extractors.R	Renames extractor tests and adds coverage for deprecated wrapper behavior.
vignettes/visual-mcmc-diagnostics.Rmd	Updates vignette narrative and examples to use extract_* and explains the rename.
man/bayesplot-extractors.Rd	Adds aliases/usages for new generics and documents rhat()/neff_ratio() as deprecated.
man/MCMC-diagnostics.Rd	Updates documentation examples/links to use extract_neff_ratio()/extract_rhat().
man/MCMC-intervals.Rd	Updates links/examples to use extract_rhat().
NAMESPACE	Exports new generics and registers their S3 methods; removes old rhat/neff_ratio method registrations.
NEWS.md	Adds a NEWS entry describing the deprecation/rename rationale.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.18%. Comparing base (9d6a95b) to head (ff85ef1).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #544   +/-   ##
=======================================
  Coverage   99.18%   99.18%           
=======================================
  Files          35       35           
  Lines        6118     6142   +24     
=======================================
+ Hits         6068     6092   +24     
  Misses         50       50           

☔ View full report in Codecov by Sentry.
📢 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.