prompt: You will be provided with a partial code base and an issue statement explaining a problem to resolve.
  <issue>
  add api docs for plot_energy
  https://arviz-devs.github.io/arviz/generated/arviz.plot_energy.html#arviz.plot_energy
  
  See Posterior Docs for example
  https://arviz-devs.github.io/arviz/generated/arviz.plot_posterior.html#arviz.plot_posterior
  
  </issue>
  <code>
  [start of arviz/plots/energyplot.py]
  1 """Plot energy transition distribution in HMC inference."""
  2 import numpy as np
  3 import matplotlib.pyplot as plt
  4 
  5 from ..data import convert_to_dataset
  6 from ..stats import bfmi as e_bfmi
  7 from .kdeplot import plot_kde
  8 from .plot_utils import _scale_fig_size
  9 
  10 
  11 def plot_energy(
  12     data,
  13     kind="kde",
  14     bfmi=True,
  15     figsize=None,
  16     legend=True,
  17     fill_alpha=(1, 0.75),
  18     fill_color=("C0", "C5"),
  19     bw=4.5,
  20     textsize=None,
  21     fill_kwargs=None,
  22     plot_kwargs=None,
  23     ax=None,
  24 ):
  25     """Plot energy transition distribution and marginal energy distribution in HMC algorithms.
  26 
  27     This may help to diagnose poor exploration by gradient-based algorithms like HMC or NUTS.
  28 
  29     Parameters
  30     ----------
  31     data : xarray dataset, or object that can be converted (must represent
  32            `sample_stats` and have an `energy` variable)
  33     kind : str
  34         Type of plot to display (kde or histogram)
  35     bfmi : bool
  36         If True add to the plot the value of the estimated Bayesian fraction of missing information
  37     figsize : tuple
  38         Figure size. If None it will be defined automatically.
  39     legend : bool
  40         Flag for plotting legend (defaults to True)
  41     fill_alpha : tuple of floats
  42         Alpha blending value for the shaded area under the curve, between 0
  43         (no shade) and 1 (opaque). Defaults to (1, .75)
  44     fill_color : tuple of valid matplotlib color
  45         Color for Marginal energy distribution and Energy transition distribution.
  46         Defaults to ('C0', 'C5')
  47     bw : float
  48         Bandwidth scaling factor for the KDE. Should be larger than 0. The higher this number the
  49         smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott's rule
  50         of thumb (the default rule used by SciPy). Only works if `kind='kde'`
  51     textsize: float
  52         Text size scaling factor for labels, titles and lines. If None it will be autoscaled based
  53         on figsize.
  54     fill_kwargs : dicts, optional
  55         Additional keywords passed to `arviz.plot_kde` (to control the shade)
  56     plot_kwargs : dicts, optional
  57         Additional keywords passed to `arviz.plot_kde` or `plt.hist` (if type='hist')
  58     ax : axes
  59         Matplotlib axes.
  60 
  61     Returns
  62     -------
  63     ax : matplotlib axes
  64     """
  65     energy = convert_to_dataset(data, group="sample_stats").energy.values
  66 
  67     if ax is None:
  68         _, ax = plt.subplots(figsize=figsize, constrained_layout=True)
  69 
  70     if fill_kwargs is None:
  71         fill_kwargs = {}
  72 
  73     if plot_kwargs is None:
  74         plot_kwargs = {}
  75 
  76     figsize, _, _, xt_labelsize, linewidth, _ = _scale_fig_size(figsize, textsize, 1, 1)
  77 
  78     series = zip(
  79         fill_alpha,
  80         fill_color,
  81         ("Marginal Energy", "Energy transition"),
  82         (energy - energy.mean(), np.diff(energy)),
  83     )
  84 
  85     if kind == "kde":
  86         for alpha, color, label, value in series:
  87             fill_kwargs["alpha"] = alpha
  88             fill_kwargs["color"] = color
  89             plot_kwargs.setdefault("color", color)
  90             plot_kwargs.setdefault("alpha", 0)
  91             plot_kwargs.setdefault("linewidth", linewidth)
  92             plot_kde(
  93                 value,
  94                 bw=bw,
  95                 label=label,
  96                 textsize=xt_labelsize,
  97                 plot_kwargs=plot_kwargs,
  98                 fill_kwargs=fill_kwargs,
  99                 ax=ax,
  100             )
  101 
  102     elif kind == "hist":
  103         for alpha, color, label, value in series:
  104             ax.hist(
  105                 value.flatten(),
  106                 bins="auto",
  107                 density=True,
  108                 alpha=alpha,
  109                 label=label,
  110                 color=color,
  111                 **plot_kwargs
  112             )
  113 
  114     else:
  115         raise ValueError("Plot type {} not recognized.".format(kind))
  116 
  117     if bfmi:
  118         for idx, val in enumerate(e_bfmi(energy)):
  119             ax.plot([], label="chain {:>2} BFMI = {:.2f}".format(idx, val), alpha=0)
  120 
  121     ax.set_xticks([])
  122     ax.set_yticks([])
  123 
  124     if legend:
  125         ax.legend()
  126 
  127     return ax
  128
  [end of arviz/plots/energyplot.py]
  </code>
  
  I need you to solve this issue by generating a single patch file that I can apply directly to this repository using git apply. Please respond with a single patch file in the following format.
  <patch>
  diff --git a/file.py b/file.py
  --- a/file.py
  +++ b/file.py
  @@ -1,27 +1,35 @@
   def euclidean(a, b):
  -    while b:
  -        a, b = b, a % b
  -    return a
  +    if b == 0:
  +        return a
  +    return euclidean(b, a % b)
   
   
   def bresenham(x0, y0, x1, y1):
       points = []
       dx = abs(x1 - x0)
       dy = abs(y1 - y0)
  -    sx = 1 if x0 < x1 else -1
  -    sy = 1 if y0 < y1 else -1
  -    err = dx - dy
  +    x, y = x0, y0
  +    sx = -1 if x0 > x1 else 1
  +    sy = -1 if y0 > y1 else 1
   
  -    while True:
  -        points.append((x0, y0))
  -        if x0 == x1 and y0 == y1:
  -            break
  -        e2 = 2 * err
  -        if e2 > -dy:
  -            err -= dy
  -            x0 += sx
  -        if e2 < dx:
  -            err += dx
  -            y0 += sy
  +    if dx > dy:
  +        err = dx / 2.0
  +        while x != x1:
  +            points.append((x, y))
  +            err -= dy
  +            if err < 0:
  +                y += sy
  +                err += dx
  +            x += sx
  +    else:
  +        err = dy / 2.0
  +        while y != y1:
  +            points.append((x, y))
  +            err -= dx
  +            if err < 0:
  +                x += sx
  +                err += dy
  +            y += sy
  +
  +    points.append((x, y))
       return points
  
  </patch>
golden_diff: diff --git a/arviz/plots/energyplot.py b/arviz/plots/energyplot.py
  --- a/arviz/plots/energyplot.py
  +++ b/arviz/plots/energyplot.py
  @@ -61,6 +61,25 @@
       Returns
       -------
       ax : matplotlib axes
  +
  +    Examples
  +    --------
  +    Plot a default energy plot
  +
  +    .. plot::
  +        :context: close-figs
  +
  +        >>> import arviz as az
  +        >>> data = az.load_arviz_data('centered_eight')
  +        >>> az.plot_energy(data)
  +
  +    Represent energy plot via histograms
  +
  +    .. plot::
  +        :context: close-figs
  +
  +        >>> az.plot_energy(data, kind='hist')
  +
       """
       energy = convert_to_dataset(data, group="sample_stats").energy.values
  
verification_info: {"golden_diff": "diff --git a/arviz/plots/energyplot.py b/arviz/plots/energyplot.py\n--- a/arviz/plots/energyplot.py\n+++ b/arviz/plots/energyplot.py\n@@ -61,6 +61,25 @@\n     Returns\n     -------\n     ax : matplotlib axes\n+\n+    Examples\n+    --------\n+    Plot a default energy plot\n+\n+    .. plot::\n+        :context: close-figs\n+\n+        >>> import arviz as az\n+        >>> data = az.load_arviz_data('centered_eight')\n+        >>> az.plot_energy(data)\n+\n+    Represent energy plot via histograms\n+\n+    .. plot::\n+        :context: close-figs\n+\n+        >>> az.plot_energy(data, kind='hist')\n+\n     \"\"\"\n     energy = convert_to_dataset(data, group=\"sample_stats\").energy.values\n", "issue": "add api docs for plot_energy\nhttps://arviz-devs.github.io/arviz/generated/arviz.plot_energy.html#arviz.plot_energy\r\n\r\nSee Posterior Docs for example\r\nhttps://arviz-devs.github.io/arviz/generated/arviz.plot_posterior.html#arviz.plot_posterior\n", "before_files": [{"content": "\"\"\"Plot energy transition distribution in HMC inference.\"\"\"\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nfrom ..data import convert_to_dataset\nfrom ..stats import bfmi as e_bfmi\nfrom .kdeplot import plot_kde\nfrom .plot_utils import _scale_fig_size\n\n\ndef plot_energy(\n    data,\n    kind=\"kde\",\n    bfmi=True,\n    figsize=None,\n    legend=True,\n    fill_alpha=(1, 0.75),\n    fill_color=(\"C0\", \"C5\"),\n    bw=4.5,\n    textsize=None,\n    fill_kwargs=None,\n    plot_kwargs=None,\n    ax=None,\n):\n    \"\"\"Plot energy transition distribution and marginal energy distribution in HMC algorithms.\n\n    This may help to diagnose poor exploration by gradient-based algorithms like HMC or NUTS.\n\n    Parameters\n    ----------\n    data : xarray dataset, or object that can be converted (must represent\n           `sample_stats` and have an `energy` variable)\n    kind : str\n        Type of plot to display (kde or histogram)\n    bfmi : bool\n        If True add to the plot the value of the estimated Bayesian fraction of missing information\n    figsize : tuple\n        Figure size. If None it will be defined automatically.\n    legend : bool\n        Flag for plotting legend (defaults to True)\n    fill_alpha : tuple of floats\n        Alpha blending value for the shaded area under the curve, between 0\n        (no shade) and 1 (opaque). Defaults to (1, .75)\n    fill_color : tuple of valid matplotlib color\n        Color for Marginal energy distribution and Energy transition distribution.\n        Defaults to ('C0', 'C5')\n    bw : float\n        Bandwidth scaling factor for the KDE. Should be larger than 0. The higher this number the\n        smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott's rule\n        of thumb (the default rule used by SciPy). Only works if `kind='kde'`\n    textsize: float\n        Text size scaling factor for labels, titles and lines. If None it will be autoscaled based\n        on figsize.\n    fill_kwargs : dicts, optional\n        Additional keywords passed to `arviz.plot_kde` (to control the shade)\n    plot_kwargs : dicts, optional\n        Additional keywords passed to `arviz.plot_kde` or `plt.hist` (if type='hist')\n    ax : axes\n        Matplotlib axes.\n\n    Returns\n    -------\n    ax : matplotlib axes\n    \"\"\"\n    energy = convert_to_dataset(data, group=\"sample_stats\").energy.values\n\n    if ax is None:\n        _, ax = plt.subplots(figsize=figsize, constrained_layout=True)\n\n    if fill_kwargs is None:\n        fill_kwargs = {}\n\n    if plot_kwargs is None:\n        plot_kwargs = {}\n\n    figsize, _, _, xt_labelsize, linewidth, _ = _scale_fig_size(figsize, textsize, 1, 1)\n\n    series = zip(\n        fill_alpha,\n        fill_color,\n        (\"Marginal Energy\", \"Energy transition\"),\n        (energy - energy.mean(), np.diff(energy)),\n    )\n\n    if kind == \"kde\":\n        for alpha, color, label, value in series:\n            fill_kwargs[\"alpha\"] = alpha\n            fill_kwargs[\"color\"] = color\n            plot_kwargs.setdefault(\"color\", color)\n            plot_kwargs.setdefault(\"alpha\", 0)\n            plot_kwargs.setdefault(\"linewidth\", linewidth)\n            plot_kde(\n                value,\n                bw=bw,\n                label=label,\n                textsize=xt_labelsize,\n                plot_kwargs=plot_kwargs,\n                fill_kwargs=fill_kwargs,\n                ax=ax,\n            )\n\n    elif kind == \"hist\":\n        for alpha, color, label, value in series:\n            ax.hist(\n                value.flatten(),\n                bins=\"auto\",\n                density=True,\n                alpha=alpha,\n                label=label,\n                color=color,\n                **plot_kwargs\n            )\n\n    else:\n        raise ValueError(\"Plot type {} not recognized.\".format(kind))\n\n    if bfmi:\n        for idx, val in enumerate(e_bfmi(energy)):\n            ax.plot([], label=\"chain {:>2} BFMI = {:.2f}\".format(idx, val), alpha=0)\n\n    ax.set_xticks([])\n    ax.set_yticks([])\n\n    if legend:\n        ax.legend()\n\n    return ax\n", "path": "arviz/plots/energyplot.py"}]}