From 4d99af56bdf17cf1f92d63bc9988130a28882b52 Mon Sep 17 00:00:00 2001 From: "Oriol (ZBook)" Date: Mon, 2 Jan 2023 21:00:44 +0100 Subject: [PATCH] fixes to docstrings --- arviz/plots/autocorrplot.py | 12 +++++----- arviz/plots/bpvplot.py | 48 +++++++++++++++++++------------------ arviz/plots/essplot.py | 28 +++++++++++----------- 3 files changed, 45 insertions(+), 43 deletions(-) diff --git a/arviz/plots/autocorrplot.py b/arviz/plots/autocorrplot.py index 55b1ddabd1..46f9114115 100644 --- a/arviz/plots/autocorrplot.py +++ b/arviz/plots/autocorrplot.py @@ -23,9 +23,9 @@ def plot_autocorr( backend_kwargs=None, show=None, ): - """Bar plot of the autocorrelation function (ACF) for a sequence of data. + r"""Bar plot of the autocorrelation function (ACF) for a sequence of data. - The ACF plots are helpful as a convergence diagnostic for posteriors from MCMC + The ACF plots are helpful as a convergence diagnostic for posteriors from MCMC samples which display autocorrelation. Parameters @@ -42,7 +42,7 @@ def plot_autocorr( interpret `var_names` as regular expressions on the real variables names. See the :ref:`this section ` for usage examples. max_lag : int, optional - Maximum lag to calculate autocorrelation. By Default, the plot displays the + Maximum lag to calculate autocorrelation. By Default, the plot displays the first 100 lag or the total number of draws, whichever is smaller. combined : bool, default False Flag for combining multiple chains into a single chain. If False, chains will be @@ -62,13 +62,13 @@ def plot_autocorr( ax : 2D array-like of matplotlib_axes or bokeh_figure, optional A 2D array of locations into which to plot the densities. If not supplied, Arviz will create its own array of plot areas (and return it). - backend : str, optional - Select plotting backend {"matplotlib","bokeh"}. Default "matplotlib". + backend : {"matplotlib", "bokeh"}, default "matplotlib" + Select plotting backend. backend_config : dict, optional Currently specifies the bounds to use for bokeh axes. Defaults to value set in ``rcParams``. backend_kwargs : dict, optional These are kwargs specific to the backend being used, passed to - :func:`matplotlib.pyplot.subplots` or :func:`bokeh.plotting.figure`. + :func:`matplotlib.pyplot.subplots` or :class:`bokeh.plotting.figure`. For additional documentation check the plotting method of the backend. show : bool, optional Call backend show function. diff --git a/arviz/plots/bpvplot.py b/arviz/plots/bpvplot.py index 07d6395b95..0a92e0aa10 100644 --- a/arviz/plots/bpvplot.py +++ b/arviz/plots/bpvplot.py @@ -36,8 +36,7 @@ def plot_bpv( group="posterior", show=None, ): - """ - Plot Bayesian p-value for observed data and Posterior/Prior predictive. + r"""Plot Bayesian p-value for observed data and Posterior/Prior predictive. Parameters ---------- @@ -47,28 +46,31 @@ def plot_bpv( kind : {"u_value", "p_value", "t_stat"}, default "u_value" Specify the kind of plot: - * The ``kind="p_value"`` computes :math:`p := p(y* \leq y | y)`. This is the probability of the - data y being larger or equal than the predicted data y*. The ideal value is 0.5 - (half the predictions below and half above the data). - * The ``kind="u_value"`` argument computes :math:`p_i := p(y_i* \leq y_i | y)`. i.e. like a p_value - but per observation :math:`y_i`. This is also known as marginal p_value. The ideal distribution - is uniform. This is similar to the LOO-pit calculation/plot, the difference is than in - LOO-pit plot we compute :math:`pi = p(y_i* r \leq y_i | y_{-i} )`, where :math:`y_{-i}`, is all - other data except :math:`y_i`. - * The ``kind="t_stat"`` argument computes :math:`:= p(T(y)* \leq T(y) | y)` where T is any test statistic. - See ``t_stat`` argument below for details of available options. - + * The ``kind="p_value"`` computes :math:`p := p(y* \leq y | y)`. + This is the probability of the data y being larger or equal than the predicted data y*. + The ideal value is 0.5 (half the predictions below and half above the data). + * The ``kind="u_value"`` argument computes :math:`p_i := p(y_i* \leq y_i | y)`. + i.e. like a p_value but per observation :math:`y_i`. This is also known as marginal + p_value. The ideal distribution is uniform. This is similar to the LOO-PIT + calculation/plot, the difference is than in LOO-pit plot we compute + :math:`pi = p(y_i* r \leq y_i | y_{-i} )`, where :math:`y_{-i}`, + is all other data except :math:`y_i`. + * The ``kind="t_stat"`` argument computes :math:`:= p(T(y)* \leq T(y) | y)` + where T is any test statistic. See ``t_stat`` argument below for details + of available options. + t_stat : str, float, or callable, default "median" - Test statistics to compute from the observations and predictive distributions. Allowed strings are - “mean”, “median” or “std”. Alternative a quantile can be passed as a float (or str) in the interval - (0, 1). Finally a user defined function is also acepted, see examples section for details. + Test statistics to compute from the observations and predictive distributions. + Allowed strings are “mean”, “median” or “std”. Alternative a quantile can be passed + as a float (or str) in the interval (0, 1). Finally a user defined function is also + acepted, see examples section for details. bpv : bool, default True If True add the Bayesian p_value to the legend when ``kind = t_stat``. plot_mean : bool, default True Whether or not to plot the mean test statistic. reference : {"analytical", "samples", None}, default "analytical" - How to compute the distributions used as reference for ``kind=u_values`` or ``kind=p_values``. - Use `None` to do not plot any reference. + How to compute the distributions used as reference for ``kind=u_values`` + or ``kind=p_values``. Use `None` to not plot any reference. mse : bool, default False Show scaled mean square error between uniform distribution and marginal p_value distribution. @@ -102,8 +104,8 @@ def plot_bpv( Class providing the method ``make_pp_label`` to generate the labels in the plot titles. Read the :ref:`label_guide` for more details and usage examples. var_names : list of str, optional - Variables to be plotted. If `None` all variable are plotted. Prefix the variables by ``~`` - when you want to exclude them from the plot. See the :ref:`this section ` + Variables to be plotted. If `None` all variable are plotted. Prefix the variables by ``~`` + when you want to exclude them from the plot. See the :ref:`this section ` for usage examples. filter_vars : {None, "like", "regex"}, default None If `None` (default), interpret `var_names` as the real variables names. If "like", @@ -137,11 +139,11 @@ def plot_bpv( and ``reference=analytical``). backend_kwargs : bool, optional These are kwargs specific to the backend being used, passed to - :func:`matplotlib.pyplot.subplots` or :func:`bokeh.plotting.figure`. + :func:`matplotlib.pyplot.subplots` or :class:`bokeh.plotting.figure`. For additional documentation check the plotting method of the backend. group : {"posterior", "prior"}, default "posterior" - Specifies which InferenceData group should be plotted. If "posterior", then the values - in `posterior_predictive` group are compared to the ones in `observed_data`, if "prior" then + Specifies which InferenceData group should be plotted. If "posterior", then the values + in `posterior_predictive` group are compared to the ones in `observed_data`, if "prior" then the same comparison happens, but with the values in `prior_predictive` group. show : bool, optional Call backend show function. diff --git a/arviz/plots/essplot.py b/arviz/plots/essplot.py index f02d120a86..66b64a4a55 100644 --- a/arviz/plots/essplot.py +++ b/arviz/plots/essplot.py @@ -37,8 +37,8 @@ def plot_ess( show=None, **kwargs, ): - """Generate quantile, local, or evolution ESS plots. - + r"""Generate quantile, local, or evolution ESS plots. + The local and the quantile ESS plots are recommended for checking that there are enough samples for all the explored regions of the parameter space. Checking local and quantile ESS is particularly @@ -47,7 +47,7 @@ def plot_ess( Parameters ---------- - idata : obj + idata : InferenceData Any object that can be converted to an :class:`arviz.InferenceData` object Refer to documentation of :func:`arviz.convert_to_dataset` for details var_names : list of str, optional @@ -61,13 +61,13 @@ def plot_ess( kind : {"local", "quantile", "evolution"}, default "local" Specify the kind of plot: - * The ``kind="local"`` argument generates the ESS' local efficiency for - estimating quantiles of a desired posterior. - * The ``kind="quantile"`` argument generates the ESS' local efficiency - for estimating small-interval probability of a desired posterior. - * The ``kind="evolution"`` argument generates the estimated ESS' - with incrised number of iterations of a desired posterior. - + * The ``kind="local"`` argument generates the ESS' local efficiency for + estimating quantiles of a desired posterior. + * The ``kind="quantile"`` argument generates the ESS' local efficiency + for estimating small-interval probability of a desired posterior. + * The ``kind="evolution"`` argument generates the estimated ESS' + with incrised number of iterations of a desired posterior. + relative : bool, default False Show relative ess in plot ``ress = ess / N``. coords : dict, optional @@ -81,7 +81,7 @@ def plot_ess( Text size scaling factor for labels, titles and lines. If None it will be autoscaled based on `figsize`. rug : bool, default False - Add a `rug plot ` for a specific subset of values. + Add a `rug plot `_ for a specific subset of values. rug_kind : str, default "diverging" Variable in sample stats to use as rug mask. Must be a boolean variable. n_points : int, default 20 @@ -113,11 +113,11 @@ def plot_ess( :func:`~matplotlib.axes.Axes.plot` or to :class:`~bokeh.plotting.figure.line` rug_kwargs : dict kwargs passed to rug plot. - backend : str, optional - Select plotting backend {"matplotlib","bokeh"}. Default "matplotlib". + backend : {"matplotlib", "bokeh"}, default "matplotlib" + Select plotting backend. backend_kwargs : dict, optional These are kwargs specific to the backend being used, passed to - :func:`matplotlib.pyplot.subplots` or :func:`bokeh.plotting.figure`. + :func:`matplotlib.pyplot.subplots` or :class:`bokeh.plotting.figure`. For additional documentation check the plotting method of the backend. show : bool, optional Call backend show function.