Refactor plot_ecdf arguments (#2316)

* Add rcparam for band probability

* Unify plot_ecdf keywords and deprecate old ones

* Change default num_trials to match plot_ecdf

* Support keywords rvs and random_state

* Deprecate values2

* Allow eval_points to be specified

* Restore original name confidence_bands

* Correctly specify ecdf usage

* Include recommended specification of eval_points

* Update examples in docstrings

* Deprecate pit keyword

* Ravel values2

* Change band_prob default to 0.95

* Run black

* Add band_prob to to rctemplate

* Use deprecation warnings

* Test deprecations

* test eval_points accepted

* Check confidence_bands args

* Test ecdfplot errors

* Update CHANGELOG.md

* Update CHANGELOG.md

* Move scipy.stats.ecdf import to top of file

* Remove duplicate warnings import

* Fix linting errors

* Add missing newline

* Mark valus2 as deprecated

* Fix bulleted list of confidence_bands options

* Clean up acceptable types for `random_state`

* Use deprecated directive for other keywords

* Make deprecation note more specific

* Deprecate `npoints`

* Move deprecated keywords to end of keywords list

* Update CHANGELOG.md

* Add missing newline

* Rename band_prob to ci_prob

* Change ci_prob default to 0.94

* Deprecate hdi_prob and replace with stats.ci_prob

* Support rvs with no keywords

* Unify docstrings

* Change deprecation warning to future warning

* Test deprecated rcparams

* Use stats.ci_prob in plots

* Use stats.ci_prob in docs

* Don't access protected class variable

* Apply suggestions from code review

changing user-facing DeprecationWarnings to FutureWarnings

* use BehaviourChangeWarning

* black and docstring updates

---------

Co-authored-by: Oriol Abril-Pla <[email protected]>

CHANGELOG.md

@@ -5,6 +5,9 @@
 ### New features
 -  Use revised Pareto k threshold ([2349](https://github.com/arviz-devs/arviz/pull/2349))
 
+-   Added arguments `ci_prob`, `eval_points`, `rvs`, and `random_state` to `plot_ecdf` ([2316](https://github.com/arviz-devs/arviz/pull/2316))
+-   Deprecated rcParam `stats.hdi_prob` and replaced with `stats.ci_prob` ([2316](https://github.com/arviz-devs/arviz/pull/2316))
+
 ### Maintenance and fixes
 - Ensure support with numpy 2.0 ([2321](https://github.com/arviz-devs/arviz/pull/2321))
 - Update testing strategy to include an environment without optional dependencies and
@@ -16,6 +19,8 @@
 -  Support for arrays and DataArrays in plot_khat has been deprecated. Only ELPDdata will be supported in the future ([2349](https://github.com/arviz-devs/arviz/pull/2349))
 
 
+-   Removed arguments `values2`, `fpr`, `pointwise`, and `pit` in `plot_ecdf` ([2316](https://github.com/arviz-devs/arviz/pull/2316))
+
 ### Documentation
 
 ## v0.18.0 (2024 Apr 4)
@@ -30,6 +35,12 @@
 - Fix deprecation warnings in multiple dependencies ([2329](https://github.com/arviz-devs/arviz/pull/2329),
   [2332](https://github.com/arviz-devs/arviz/pull/2332) and [2333](https://github.com/arviz-devs/arviz/pull/2333))
 
+### Deprecation
+
+-   Removed arguments `values2`, `fpr`, `pointwise`, `npoints`, and `pit` in `plot_ecdf` ([2316](https://github.com/arviz-devs/arviz/pull/2316))
+
+### Documentation
+
 ## v0.17.1 (2024 Mar 13)
 
 ### Maintenance and fixes

arviz/plots/backends/bokeh/ecdfplot.py

@@ -13,7 +13,6 @@ def plot_ecdf(
     x_bands,
     lower,
     higher,
-    confidence_bands,
     plot_kwargs,
     fill_kwargs,
     plot_outline_kwargs,
@@ -58,7 +57,7 @@ def plot_ecdf(
         plot_outline_kwargs.setdefault("color", to_hex("C0"))
         plot_outline_kwargs.setdefault("alpha", 0.2)
 
-    if confidence_bands:
+    if x_bands is not None:
         ax.step(x_coord, y_coord, **plot_kwargs)
 
         if fill_band:

arviz/plots/backends/matplotlib/ecdfplot.py

@@ -13,7 +13,6 @@ def plot_ecdf(
     x_bands,
     lower,
     higher,
-    confidence_bands,
     plot_kwargs,
     fill_kwargs,
     plot_outline_kwargs,
@@ -59,7 +58,7 @@ def plot_ecdf(
 
     ax.step(x_coord, y_coord, **plot_kwargs)
 
-    if confidence_bands:
+    if x_bands is not None:
         if fill_band:
             ax.fill_between(x_bands, lower, higher, **fill_kwargs)
         else:

arviz/plots/bpvplot.py

@@ -80,7 +80,7 @@ def plot_bpv(
     hdi_prob : float, optional
         Probability for the highest density interval for the analytical reference distribution when
         ``kind=u_values``. Should be in the interval (0, 1]. Defaults to the
-        rcParam ``stats.hdi_prob``. See :ref:`this section <common_hdi_prob>` for usage examples.
+        rcParam ``stats.ci_prob``. See :ref:`this section <common_hdi_prob>` for usage examples.
     color : str, optional
         Matplotlib color
     grid : tuple, optional
@@ -202,7 +202,7 @@ def plot_bpv(
         raise TypeError("`reference` argument must be either `analytical`, `samples`, or `None`")
 
     if hdi_prob is None:
-        hdi_prob = rcParams["stats.hdi_prob"]
+        hdi_prob = rcParams["stats.ci_prob"]
     elif not 1 >= hdi_prob > 0:
         raise ValueError("The value of hdi_prob should be in the interval (0, 1]")
 

arviz/plots/densityplot.py

@@ -209,7 +209,7 @@ def plot_density(
         )
 
     if hdi_prob is None:
-        hdi_prob = rcParams["stats.hdi_prob"]
+        hdi_prob = rcParams["stats.ci_prob"]
     elif not 1 >= hdi_prob > 0:
         raise ValueError("The value of hdi_prob should be in the interval (0, 1]")
 

arviz/plots/dotplot.py

@@ -67,7 +67,7 @@ def plot_dot(
         The shape of the marker. Valid for matplotlib backend.
     hdi_prob : float, optional
         Valid only when point_interval is True. Plots HDI for chosen percentage of density.
-        Defaults to ``stats.hdi_prob`` rcParam. See :ref:`this section <common_hdi_prob>`
+        Defaults to ``stats.ci_prob`` rcParam. See :ref:`this section <common_hdi_prob>`
         for usage examples.
     rotated : bool, default False
         Whether to rotate the dot plot by 90 degrees.
@@ -151,7 +151,7 @@ def plot_dot(
     values.sort()
 
     if hdi_prob is None:
-        hdi_prob = rcParams["stats.hdi_prob"]
+        hdi_prob = rcParams["stats.ci_prob"]
     elif not 1 >= hdi_prob > 0:
         raise ValueError("The value of hdi_prob should be in the interval (0, 1]")