Use only is_circular argument in plot_dist (arviz-devs#1681)

* use only is_circular argument

* change xlabels

* update posteriorplot and traceplot

* update bokeh plots

* add internal conversion for inputs in degrees

* update changelog and docstrings

CHANGELOG.md

@@ -32,6 +32,7 @@
 * Added type checking to raise an error whenever `InferenceData` object is passed using `io_pymc3`'s `trace` argument ([1629](https://github.com/arviz-devs/arviz/pull/1629))
 * Fix `xlabels` in `plot_elpd` ([1601](https://github.com/arviz-devs/arviz/pull/1601))
 * Renamed `sample` dim to `__sample__` when stacking `chain` and `draw` to avoid dimension collision ([1647](https://github.com/arviz-devs/arviz/pull/1647))
+* Removed the `circular` argument in `plot_dist` in favor of `is_circular` ([1681](https://github.com/arviz-devs/arviz/pull/1681))
 
 ### Deprecation
 * Deprecated `index_origin` and `order` arguments in `az.summary` ([1201](https://github.com/arviz-devs/arviz/pull/1201))

arviz/plots/backends/bokeh/distplot.py

@@ -19,7 +19,6 @@ def plot_dist(
     rotated,
     rug,
     bw,
-    circular,
     quantiles,
     contour,
     fill_last,
@@ -95,7 +94,7 @@ def plot_dist(
             rug=rug,
             label=label,
             bw=bw,
-            circular=circular,
+            is_circular=is_circular,
             quantiles=quantiles,
             rotated=rotated,
             contour=contour,

arviz/plots/backends/bokeh/posteriorplot.py

@@ -276,7 +276,7 @@ def format_axes():
         plot_kde(
             values,
             bw=bw,
-            circular=circular,
+            is_circular=circular,
             fill_kwargs={"fill_alpha": kwargs.pop("fill_alpha", 0)},
             plot_kwargs=kwargs,
             ax=ax,

arviz/plots/backends/matplotlib/distplot.py

@@ -19,7 +19,6 @@ def plot_dist(
     rotated,
     rug,
     bw,
-    circular,
     quantiles,
     contour,
     fill_last,
@@ -98,7 +97,6 @@ def plot_dist(
             rug=rug,
             label=label,
             bw=bw,
-            circular=circular,
             quantiles=quantiles,
             rotated=rotated,
             contour=contour,
@@ -136,14 +134,14 @@ def _histplot_mpl_op(values, values2, rotated, ax, hist_kwargs, is_circular):
 
     elif is_circular:
         labels = [
-            r"0",
-            r"π/4",
-            r"π/2",
-            r"3π/4",
-            r"π",
-            r"5π/4",
-            r"3π/2",
-            r"7π/4",
+            "0",
+            f"{np.pi/4:.2f}",
+            f"{np.pi/2:.2f}",
+            f"{3*np.pi/4:.2f}",
+            f"{np.pi:.2f}",
+            f"{-3*np.pi/4:.2f}",
+            f"{-np.pi/2:.2f}",
+            f"{-np.pi/4:.2f}",
         ]
 
         ax.set_xticklabels(labels)

arviz/plots/backends/matplotlib/posteriorplot.py

@@ -312,7 +312,7 @@ def format_axes():
         plot_kde(
             values,
             bw=bw,
-            circular=circular,
+            is_circular=circular,
             fill_kwargs={"alpha": kwargs.pop("fill_alpha", 0)},
             plot_kwargs=kwargs,
             ax=ax,

arviz/plots/backends/matplotlib/traceplot.py

@@ -499,7 +499,6 @@ def _plot_chains_mpl(
                     backend="matplotlib",
                     show=False,
                     is_circular=circ_var_units,
-                    circular=circular,
                 )
 
     if kind == "rank_bars" and idy:
@@ -522,6 +521,5 @@ def _plot_chains_mpl(
                 backend="matplotlib",
                 show=False,
                 is_circular=circ_var_units,
-                circular=circular,
             )
     return axes

arviz/plots/distplot.py

@@ -18,7 +18,6 @@ def plot_dist(
     rotated=False,
     rug=False,
     bw="default",
-    circular=False,
     quantiles=None,
     contour=True,
     fill_last=True,
@@ -66,13 +65,10 @@ def plot_dist(
     bw: Optional[float or str]
         If numeric, indicates the bandwidth and must be positive.
         If str, indicates the method to estimate the bandwidth and must be
-        one of "scott", "silverman", "isj" or "experimental" when `circular` is False
-        and "taylor" (for now) when `circular` is True.
+        one of "scott", "silverman", "isj" or "experimental" when `is_circular` is False
+        and "taylor" (for now) when `is_circular` is True.
         Defaults to "default" which means "experimental" when variable is not circular
         and "taylor" when it is.
-    circular: Optional[bool]
-        If True, it interprets the values passed are from a circular variable measured in radians
-        and a circular KDE is used. Only valid for 1D KDE. Defaults to False.
     quantiles : list
         Quantiles in ascending order used to segment the KDE. Use [.25, .5, .75] for quartiles.
         Defaults to None.
@@ -104,7 +100,10 @@ def plot_dist(
         Keywords passed to the histogram.
     is_circular : {False, True, "radians", "degrees"}. Default False.
         Select input type {"radians", "degrees"} for circular histogram or KDE plot. If True,
-        default input type is "radians".
+        default input type is "radians". When this argument is present, it interprets the
+        values passed are from a circular variable measured in radians and a circular KDE is
+        used. Inputs in "degrees" will undergo an internal conversion to radians. Only valid
+        for 1D KDE. Defaults to False.
     ax: axes, optional
         Matplotlib axes or bokeh figures.
     backend: str, optional
@@ -186,7 +185,6 @@ def plot_dist(
         rotated=rotated,
         rug=rug,
         bw=bw,
-        circular=circular,
         quantiles=quantiles,
         contour=contour,
         fill_last=fill_last,

arviz/plots/kdeplot.py

@@ -16,7 +16,6 @@ def plot_kde(
     label=None,
     bw="default",
     adaptive=False,
-    circular=False,
     quantiles=None,
     rotated=False,
     contour=True,
@@ -56,16 +55,13 @@ def plot_kde(
     bw: float or str, optional
         If numeric, indicates the bandwidth and must be positive.
         If str, indicates the method to estimate the bandwidth and must be
-        one of "scott", "silverman", "isj" or "experimental" when `circular` is False
-        and "taylor" (for now) when `circular` is True.
+        one of "scott", "silverman", "isj" or "experimental" when `is_circular` is False
+        and "taylor" (for now) when `is_circular` is True.
         Defaults to "default" which means "experimental" when variable is not circular
         and "taylor" when it is.
     adaptive: bool, optional.
         If True, an adaptative bandwidth is used. Only valid for 1D KDE.
         Defaults to False.
-    circular: bool, optional.
-        If True, it interprets `values` is a circular variable measured in radians
-        and a circular KDE is used. Only valid for 1D KDE. Defaults to False.
     quantiles : list
         Quantiles in ascending order used to segment the KDE.
         Use [.25, .5, .75] for quartiles. Defaults to None.
@@ -99,7 +95,9 @@ def plot_kde(
         Keywords passed to ax.pcolormesh. Ignored for 1D KDE.
     is_circular : {False, True, "radians", "degrees"}. Default False.
         Select input type {"radians", "degrees"} for circular histogram or KDE plot. If True,
-        default input type is "radians".
+        default input type is "radians". When this argument is present, it interprets `values`
+        is a circular variable measured in radians and a circular KDE is used. Inputs in
+        "degrees" will undergo an internal conversion to radians.
     ax: axes, optional
         Matplotlib axes or bokeh figures.
     legend : bool
@@ -169,7 +167,7 @@ def plot_kde(
         :context: close-figs
 
         >>> rvs = np.random.vonmises(mu=np.pi, kappa=2, size=500)
-        >>> az.plot_kde(rvs, circular=True)
+        >>> az.plot_kde(rvs, is_circular=True)
 
 
     Plot a cumulative distribution
@@ -242,12 +240,12 @@ def plot_kde(
     if values2 is None:
 
         if bw == "default":
-            if circular:
+            if is_circular:
                 bw = "taylor"
             else:
                 bw = "experimental"
 
-        grid, density = kde(values, circular, bw=bw, adaptive=adaptive, cumulative=cumulative)
+        grid, density = kde(values, is_circular, bw=bw, adaptive=adaptive, cumulative=cumulative)
         lower, upper = grid[0], grid[-1]
 
         if cumulative:

arviz/stats/density_utils.py

@@ -522,6 +522,8 @@ def kde(x, circular=False, **kwargs):
     arviz.stats.density_utils.kde: Arviz KDE estimator
     """
     if circular:
+        if circular == "degrees":
+            x = np.radians(x)
         kde_fun = _kde_circular
     else:
         kde_fun = _kde_linear
@@ -662,7 +664,7 @@ def _kde_circular(
     ----------
     x : 1D numpy array
         Data used to calculate the density estimation.
-        Theoritically it is a random sample obtained from $f$,
+        Theoretically it is a random sample obtained from $f$,
         the true probability density function we aim to estimate.
     bw: int, float or str, optional
         If numeric, indicates the bandwidth and must be positive.