diff --git a/docs/source/gallery/backreferences.json b/docs/source/gallery/backreferences.json index f465a28..44b2f45 100644 --- a/docs/source/gallery/backreferences.json +++ b/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"}]} \ No newline at end of file +{"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"}]} \ No newline at end of file diff --git a/docs/source/gallery/inference_diagnostics/plot_mcse.py b/docs/source/gallery/inference_diagnostics/plot_mcse.py new file mode 100644 index 0000000..0e9006b --- /dev/null +++ b/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() diff --git a/docs/source/gallery/inference_diagnostics/plot_mcse_errorbar.py b/docs/source/gallery/inference_diagnostics/plot_mcse_errorbar.py new file mode 100644 index 0000000..c1ad999 --- /dev/null +++ b/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() diff --git a/docs/source/gallery/inference_diagnostics/plot_mcse_models.py b/docs/source/gallery/inference_diagnostics/plot_mcse_models.py new file mode 100644 index 0000000..0257ecd --- /dev/null +++ b/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() diff --git a/docs/source/gallery/inference_diagnostics/plot_mcse_models_errorbar.py b/docs/source/gallery/inference_diagnostics/plot_mcse_models_errorbar.py new file mode 100644 index 0000000..0788f5d --- /dev/null +++ b/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() diff --git a/src/arviz_plots/plots/mcseplot.py b/src/arviz_plots/plots/mcseplot.py index 674d03b..359bd70 100644 --- a/src/arviz_plots/plots/mcseplot.py +++ b/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: