Added docs

docs/source/gallery/backreferences.json

@@ -1 +1 @@
-{"plot_forest": [{"basename": "plot_forest_ess", "refname": "gallery_forest_ess", "title": "Forest plot with ESS", "description": "Multiple panel visualization with a forest plot and ESS information"}, {"basename": "plot_forest", "refname": "gallery_forest", "title": "Forest plot", "description": "Default forest plot with marginal distribution summaries"}, {"basename": "plot_forest_shade", "refname": "gallery_forest_shade", "title": "Forest plot with shading", "description": "Forest plot marginal summaries with row shading to enhance reading"}, {"basename": "plot_forest_models", "refname": "gallery_forest_models", "title": "Forest plot comparison", "description": "Forest plot summaries for 1D marginal distributions"}, {"basename": "plot_forest_pp_obs", "refname": "gallery_forest_pp_obs", "title": "Posterior predictive and observations forest plot", "description": "Overlay of forest plot for the posterior predictive samples and the actual observations"}], "plot_dist": [{"basename": "plot_dist_ecdf", "refname": "gallery_dist_ecdf", "title": "ECDF plot", "description": "Facetted ECDF plots for 1D marginals of the distribution"}, {"basename": "plot_dist_hist", "refname": "gallery_dist_hist", "title": "Histogram plot", "description": "Facetted histogram plots for 1D marginals of the distribution"}, {"basename": "plot_dist_kde", "refname": "gallery_dist_kde", "title": "KDE plot", "description": "Facetted KDE plots for 1D marginals of the distribution"}, {"basename": "plot_dist_models", "refname": "gallery_dist_models", "title": "Marginal distribution comparison plot", "description": "Full marginal distribution comparison between different models"}], "plot_trace": [{"basename": "plot_trace", "refname": "gallery_trace", "title": "Trace plot", "description": "Facetted plot with MCMC traces for each variable"}]}
+{"plot_forest": [{"basename": "plot_forest_ess", "refname": "gallery_forest_ess", "title": "Forest plot with ESS", "description": "Multiple panel visualization with a forest plot and ESS information"}, {"basename": "plot_forest", "refname": "gallery_forest", "title": "Forest plot", "description": "Default forest plot with marginal distribution summaries"}, {"basename": "plot_forest_shade", "refname": "gallery_forest_shade", "title": "Forest plot with shading", "description": "Forest plot marginal summaries with row shading to enhance reading"}, {"basename": "plot_forest_models", "refname": "gallery_forest_models", "title": "Forest plot comparison", "description": "Forest plot summaries for 1D marginal distributions"}, {"basename": "plot_forest_pp_obs", "refname": "gallery_forest_pp_obs", "title": "Posterior predictive and observations forest plot", "description": "Overlay of forest plot for the posterior predictive samples and the actual observations"}], "plot_dist": [{"basename": "plot_dist_ecdf", "refname": "gallery_dist_ecdf", "title": "ECDF plot", "description": "Facetted ECDF plots for 1D marginals of the distribution"}, {"basename": "plot_dist_hist", "refname": "gallery_dist_hist", "title": "Histogram plot", "description": "Facetted histogram plots for 1D marginals of the distribution"}, {"basename": "plot_dist_kde", "refname": "gallery_dist_kde", "title": "KDE plot", "description": "Facetted KDE plots for 1D marginals of the distribution"}, {"basename": "plot_dist_models", "refname": "gallery_dist_models", "title": "Marginal distribution comparison plot", "description": "Full marginal distribution comparison between different models"}], "plot_mcse": [{"basename": "plot_mcse", "refname": "gallery_mcse", "title": "MCSE Quantile plot", "description": "Facetted quantile MCSE plot"}, {"basename": "plot_mcse_errorbar", "refname": "gallery_mcse_errorbar", "title": "MCSE Quantile plot with errorbars", "description": "Facetted quantile MCSE plot with errorbars"}, {"basename": "plot_mcse_models", "refname": "gallery_mcse_models", "title": "MCSE comparison plot", "description": "Full MCSE comparison between different models"}], "plot_trace": [{"basename": "plot_trace", "refname": "gallery_trace", "title": "Trace plot", "description": "Facetted plot with MCMC traces for each variable"}]}

docs/source/gallery/inference_diagnostics/plot_mcse.py

@@ -0,0 +1,24 @@
+"""
+# MCSE Quantile plot
+
+Facetted quantile MCSE plot
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_mcse`
+:::
+"""
+
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+data = load_arviz_data("centered_eight")
+pc = azp.plot_mcse(
+    data,
+    backend="none",  # change to preferred backend
+)
+pc.show()

docs/source/gallery/inference_diagnostics/plot_mcse_errorbar.py

@@ -0,0 +1,25 @@
+"""
+# MCSE Quantile plot with errorbars
+
+Facetted quantile MCSE plot with errorbars
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_mcse`
+:::
+"""
+
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+data = load_arviz_data("centered_eight")
+pc = azp.plot_mcse(
+    data,
+    errorbar=True,
+    backend="none",  # change to preferred backend
+)
+pc.show()

docs/source/gallery/inference_diagnostics/plot_mcse_models.py

@@ -0,0 +1,25 @@
+"""
+# MCSE comparison plot
+
+Full MCSE comparison between different models
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_mcse`
+:::
+"""
+
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+c = load_arviz_data("centered_eight")
+n = load_arviz_data("non_centered_eight")
+pc = azp.plot_mcse(
+    {"Centered": c, "Non Centered": n},
+    backend="none",  # change to preferred backend
+)
+pc.show()

docs/source/gallery/inference_diagnostics/plot_mcse_models_errorbar.py

@@ -0,0 +1,26 @@
+"""
+# MCSE comparison plot with errorbars
+
+Full MCSE comparison between different models with errorbars
+
+---
+
+:::{seealso}
+API Documentation: {func}`~arviz_plots.plot_mcse`
+:::
+"""
+
+from arviz_base import load_arviz_data
+
+import arviz_plots as azp
+
+azp.style.use("arviz-clean")
+
+c = load_arviz_data("centered_eight")
+n = load_arviz_data("non_centered_eight")
+pc = azp.plot_mcse(
+    {"Centered": c, "Non Centered": n},
+    errorbar=True,
+    backend="none",  # change to preferred backend
+)
+pc.show()

src/arviz_plots/plots/mcseplot.py

@@ -119,6 +119,80 @@ def plot_mcse(
     -------
     PlotCollection
 
+    Examples
+    --------
+    The following examples focus on behaviour specific to ``plot_mcse``.
+    For a general introduction to batteries-included functions like this one and common
+    usage examples see :ref:`plots_intro`
+
+    Default plot_mcse for a single model:
+
+    .. plot::
+        :context: close-figs
+        >>> from arviz_plots import plot_mcse, style
+        >>> style.use("arviz-clean")
+        >>> from arviz_base import load_arviz_data
+        >>> centered = load_arviz_data('centered_eight')
+        >>> non_centered = load_arviz_data('non_centered_eight')
+        >>> pc = plot_mcse(centered)
+
+    Default plot_mcse for multiple models: (Depending on the number of models, a slight
+    x-axis separation aesthetic is applied for each mcse point for distinguishability in
+    case of overlap)
+
+    .. plot::
+        :context: close-figs
+        >>> pc = plot_mcse(
+        >>>     {"centered": centered, "non centered": non_centered},
+        >>>     coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
+        >>> )
+        >>> pc.add_legend("model")
+
+    We can also manually map the color to the variable, and have the mapping apply
+    to the title too instead of only the mcse markers:
+
+    .. plot::
+        :context: close-figs
+        >>> pc = plot_mcse(
+        >>>     non_centered,
+        >>>     coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
+        >>>     pc_kwargs={"aes": {"color": ["__variable__"]}},
+        >>>     aes_map={"title": ["color"]},
+        >>> )
+
+    If we add a mapping (like color) manually to the variable, but not specify which artist
+    to apply the mapping to- then it is applied to the 'mcse' marker artist by default:
+
+    .. plot::
+        :context: close-figs
+        >>> pc = plot_mcse(
+        >>>     centered,
+        >>>     coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
+        >>>     pc_kwargs={"aes": {"color": ["__variable__"]}},
+        >>> )
+
+    The artists' visual features can also be customized through plot_kwargs, based on the
+    kwargs that the visual element function for the artist accepts- like all the other
+    batteries included plots. For example, for the 'mcse' artist, the scatter_xy function or
+    errorbar function is used. So if we want to change the marker:
+
+    .. plot::
+        :context: close-figs
+        >>> pc = plot_mcse(
+        >>>    centered,
+        >>>    coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
+        >>>    plot_kwargs={"mcse": {"marker": "_"}},
+        >>> )
+
+    .. plot::
+        :context: close-figs
+        >>> pc = plot_mcse(
+        >>>    centered,
+        >>>    coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
+        >>>    plot_kwargs={"mcse": {"marker": "_"}},
+        >>>    errorbar=True,
+        >>> )
+
     """
     # initial defaults
     if sample_dims is None: