# hist.plot module

### hist.plot.hist2dplot(H, xbins=None, ybins=None, labels=None, labels_fontsize=None, labels_round=None, labels_color=None, cbar: [bool](https://docs.python.org/3/builtins/functions.html#bool) = True, cbarsize='7%', cbarpad=0.2, cbarpos='right', cbarextend=None, cmin=None, cmax=None, mask=None, ax: Axes | [None](https://docs.python.org/3/builtins/constants.html#None) = None, flow='hint', binwnorm=None, \*\*kwargs)

Create a 2D histogram plot from np.histogram-like inputs.

* **Parameters:**
  * **H** ([*object*](https://docs.python.org/3/builtins/functions.html#object)) – 

    Histogram object with containing values and optionally bins. Can be:
    - np.histogram tuple
    - boost_histogram histogram object
    - raw histogram values as list of list or 2d-array
  * **xbins** (*1D array-like* *,* *optional* *,* *default None*) – Histogram bins along x axis, if not part of `H`.
  * **ybins** (*1D array-like* *,* *optional* *,* *default None*) – Histogram bins along y axis, if not part of `H`.
  * **labels** (*2D array* *(**H-like* *) or* [*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *default None* *,* *optional*) – Array of per-bin labels to display. If `True` will
    display numerical values
  * **labels_fontsize** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional* *,* *default None*) – Fontsize of labels.
  * **labels_color** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional* *,* *default None*) – Color of labels. If not given, will be decided automatically.
  * **labels_round** ([*int*](https://docs.python.org/3/builtins/functions.html#int) *,* *optional* *,* *default None*) – Round labels to given number of decimals
  * **cbar** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *optional* *,* *default True*) – Draw a colorbar. In contrast to mpl behaviors the cbar axes is
    appended in such a way that it doesn’t modify the original axes
    width:height ratio.
  * **cbarsize** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *or* [*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional* *,* *default "7%"*) – Colorbar width.
  * **cbarpad** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional* *,* *default 0.2*) – Colorbar distance from main axis.
  * **cbarpos** ( *{'right'* *,*  *'left'* *,*  *'bottom'* *,*  *'top'}* *,* *optional* *,*  *default "right"*) – Colorbar position w.r.t main axis.
  * **cbarextend** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *optional* *,* *default None* *(**auto* *)*) – Extends figure size to keep original axes size same as without cbar.
    If None (default), automatically set to True for single-axes figures
    and False for multi-axes figures to prevent layout issues.
  * **cmin** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – Colorbar minimum.
  * **cmax** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – Colorbar maximum.
  * **mask** (*2D array* *(**H-like* *)* *,* *optional*) – Boolean mask to hide cells. Cells with False value are not shown.
  * **ax** (*matplotlib.axes.Axes* *,* *optional*) – Axes object (if None, last one is fetched or one is created)
  * **flow** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional {"show"* *,*  *"sum"* *,* *"hint"* *,* *None}*) – Whether plot the under/overflow bin. If “show”, add additional under/overflow bin. If “sum”, add the under/overflow bin content to first/last bin. “hint” would highlight the bins with under/overflow contents
  * **binwnorm** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – 

    If true, convert sum weights to bin-width-normalized, with unit equal to
    : supplied value (usually you want to specify 1.)
  * **\*\*kwargs** – Keyword arguments passed to underlying matplotlib function - pcolormesh.
* **Return type:**
  Hist2DArtist

### hist.plot.histplot(H, bins=None, , yerr: ArrayLike | [bool](https://docs.python.org/3/builtins/functions.html#bool) | [None](https://docs.python.org/3/builtins/constants.html#None) = None, w2=None, w2method=None, stack: [bool](https://docs.python.org/3/builtins/functions.html#bool) = False, density: [bool](https://docs.python.org/3/builtins/functions.html#bool) = False, binwnorm=None, histtype: [str](https://docs.python.org/3/builtins/stdtypes.html#str) = 'step', xerr=False, label=None, sort=None, edges=True, binticks=False, xoffsets=None, ax: mpl.axes.Axes | [None](https://docs.python.org/3/builtins/constants.html#None) = None, flow='hint', blind=None, \*\*kwargs)

Create a 1D histogram plot from np.histogram-like inputs.

* **Parameters:**
  * **H** ([*object*](https://docs.python.org/3/builtins/functions.html#object)) – 

    Histogram object with containing values and optionally bins. Can be:
    - np.histogram tuple
    - PlottableProtocol histogram object
    - boost_histogram classic (<0.13) histogram object
    - raw histogram values, provided bins is specified.

    Or list thereof.
  * **bins** (*iterable* *,* *optional*) – Histogram bins, if not part of `H`.
  * **yerr** (*iterable* *or* [*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *optional*) – Histogram uncertainties. Following modes are supported:
    - True, sqrt(N) errors or poissonian interval when `w2` is specified
    - shape(N) array of for one sided errors or list thereof
    - shape(Nx2) array of for two sided errors or list thereof
  * **w2method** (*callable* *,* *optional*) – Function calculating CLs with signature `low, high = fcn(w, w2)`. Here
    `low` and `high` are given in absolute terms, not relative to w.
    Default is `None`. If w2 has integer values (likely to be data) poisson
    interval is calculated, otherwise the resulting error is symmetric
    `sqrt(w2)`. Specifying `poisson` or `sqrt` will force that behaviours.
  * **stack** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *optional*) – Whether to stack or overlay non-axis dimension (if it exists). N.B. in
    contrast to ROOT, stacking is performed in a single call aka
    `histplot([h1, h2, ...], stack=True)` as opposed to multiple calls.
  * **density** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *optional*) – If true, convert sum weights to probability density (i.e. integrates to 1
    over domain of axis) (Note: this option conflicts with `binwnorm`)
  * **binwnorm** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – 

    If true, convert sum weights to bin-width-normalized, with unit equal to
    : supplied value (usually you want to specify 1.)
  * **histtype** ( *{'step'* *,*  *'fill'* *,*  *'errorbar'* *,*  *'bar'* *,*  *'barstep'* *,*  *'band'}* *,* *optional* *,* *default: "step"*) – 

    Type of histogram to plot:
    - ”step”: skyline/step/outline of a histogram using [plt.stairs]([https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stairs.html#matplotlib-axes-axes-stairs](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stairs.html#matplotlib-axes-axes-stairs)).
    - ”fill”: filled histogram using [plt.stairs]([https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stairs.html#matplotlib-axes-axes-stairs](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stairs.html#matplotlib-axes-axes-stairs)).
    - ”errorbar”: single marker histogram using [plt.errorbar]([https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.errorbar.html#matplotlib-axes-axes-errorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.errorbar.html#matplotlib-axes-axes-errorbar)).
    - ”bar”: If multiple data are given the bars are arranged side by side using [plt.bar]([https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.bar.html#matplotlib-axes-axes-bar](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.bar.html#matplotlib-axes-axes-bar)). If only one histogram is provided, it will be treated as “fill” histtype.
    - ”barstep”: If multiple data are given the steps are arranged side by side using [plt.stairs]([https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stairs.html#matplotlib-axes-axes-stairs](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stairs.html#matplotlib-axes-axes-stairs)). Supports yerr representation. If one histogram is provided, it will be treated as “step” histtype.
    - ”band”: filled band spanning the yerr range of the histogram using [plt.stairs]([https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stairs.html#matplotlib-axes-axes-stairs](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stairs.html#matplotlib-axes-axes-stairs)).
  * **label** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *or* [*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *,* *optional*) – Label for legend entry.
  * **sort** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional {'label'/'l'* *,*  *'yield'/'y'}*) – “label”/”l”: sort histograms alphabetically by label, “yield”/”y”: sort by total histogram yield. Append ‘_r’ to reverse the order.
  * **ax** (*matplotlib.axes.Axes* *,* *optional*) – Axes object (if None, last one is fetched or one is created)
  * **flow** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional { "show"* *,*  *"sum"* *,*  *"hint"* *,*  *"none"}*) – Whether plot the under/overflow bin. If “show”, add additional under/overflow bin.
    If “sum”, add the under/overflow bin content to first/last bin.
    If “hint”, draw markers at the axis to indicate presence of under/overflow.
    If “none”, do nothing.
  * **blind** ([*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple) *,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* [*slice*](https://docs.python.org/3/builtins/functions.html#slice) *, or* *list thereof* *,* *optional*) – 

    Region(s) to blind (hide) in the histogram. Blinded bins are set to NaN,
    creating visual gaps. Supports:
    - `int`: single bin index to blind; a list of ints `[2, 5, 7]` blinds
      those individual bins.
    - Tuple `(lo, hi)`: value-based, blinds bins overlapping `[lo, hi)`.
    - String `"100j:200j"`: `j` suffix for value-based; `"3:7"` for
      index-based; `"5:10j"` for mixed (index start, value stop).
    - `mplhep.loc[lo:hi]`: value-based via the `mplhep.loc` helper.
      `mplhep.loc[5:10j]` for mixed (index 5 start, value 10 stop).
    - `slice(100j, 200j)`: value-based via complex numbers (UHI convention).
    - `slice(3, 7)`: index-based.
    - `slice(3, 70j)`: mixed (index start, value stop).
    - A list of any of the above to blind multiple regions.
  * **\*\*kwargs** – Keyword arguments passed to underlying matplotlib functions -
    {‘stairs’, ‘errorbar’}.
  * **w2** (*iterable* *,* *optional*) – Sum of the histogram weights squared for poissonian interval error
    calculation
  * **xerr** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *or* [*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – Size of xerr if `histtype == 'errorbar'`. If `True`, bin-width will be used.
  * **edges** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *default: True* *,* *optional*) – Specifies whether to draw first and last edges of the histogram.
  * **binticks** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *default: False* *,* *optional*) – Attempts to draw x-axis ticks coinciding with bin boundaries if feasible.
  * **xoffsets** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *default: False* *,*) – If True, the bin “centers” of plotted histograms will be offset within their bin.
  * **bar_bin_width** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *default: 0.8*) – Only used for `histtype="bar"` and `histtype="barstep"`. Fraction of
    each bin’s width occupied by the group of side-by-side bars (e.g. `0.8`
    leaves a 20% gap between adjacent bins). Scaled per-bin, so variable-width
    bins are handled correctly.
* **Return type:**
  List[Hist1DArtists]

### hist.plot.plot2d_full(self: [BaseHist](hist.basehist.html.md#hist.basehist.BaseHist)[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], , ax_dict: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), Axes] | [None](https://docs.python.org/3/builtins/constants.html#None) = None, \*\*kwargs: [Any](https://docs.python.org/3/library/typing.html#typing.Any)) → [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[ColormeshArtists, StairsArtists | ErrorBarArtists, StairsArtists | ErrorBarArtists]

Plot2d_full method for BaseHist object.

Pass a dict of axes to `ax_dict`, otherwise, the current figure will be used.

* **Parameters:**
  * **main_\*** (*optional*) – Keywords arguments prefixed with ‘’

    ```
    main_
    ```

    ’’ are forwarded to the main 2D histogram
    plot and controls its appearance.
  * **top_\*** (*optional*) – Keywords arguments prefixed with ‘’

    ```
    top_
    ```

    ’’ are forwarded to the top histogram plot and controls
    its appearance.
  * **side_\*** (*optional*) – Keywords arguments prefixed with ‘’

    ```
    side_
    ```

    ’’ are forwarded to the side histogram plot
    and controls its appearance.

### hist.plot.plot_pie(self: [BaseHist](hist.basehist.html.md#hist.basehist.BaseHist)[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], , ax: Axes | [None](https://docs.python.org/3/builtins/constants.html#None) = None, \*\*kwargs: [Any](https://docs.python.org/3/library/typing.html#typing.Any)) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

### hist.plot.plot_pull_array(hist_: [BaseHist](hist.basehist.html.md#hist.basehist.BaseHist)[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], pulls: NDArray[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], ax: Axes, bar_kwargs: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)], pp_kwargs: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]) → PullArtists

Plot a pull plot on the given axes

### hist.plot.plot_ratio_array(hist_: [BaseHist](hist.basehist.html.md#hist.basehist.BaseHist)[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], ratio: NDArray[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], ratio_uncert: NDArray[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], ax: Axes, \*\*kwargs: [Any](https://docs.python.org/3/library/typing.html#typing.Any)) → RatioErrorbarArtists | RatioBarArtists

Plot a ratio plot on the given axes

* **Parameters:**
  * **central_value** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – Value of Y-axis at which to draw the horizontal reference line
    on the ration plot.
    Default is 1.0.
  * **uncert_draw_type** ( *{"line"* *,*  *"bar"}* *,* *optional*) – Defines how uncertainty is drawn on the ration plot.
    If “line”, uncertainty is shown as error bars.
    If “bar”, uncertainty is shown as bars.
    Default is “line”.
  * **ylim** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple) *of* [*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – Y-axis limits for the ratio plot given as (ymin, ymax)
    If not provided, limits are automatically determined based on
    the ratio values and their uncertainties.

### hist.plot.plot_stack(self: [Stack](hist.stack.html.md#hist.stack.Stack)[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], , ax: Axes | [None](https://docs.python.org/3/builtins/constants.html#None) = None, legend: [bool](https://docs.python.org/3/builtins/functions.html#bool) | [None](https://docs.python.org/3/builtins/constants.html#None) = False, \*\*kwargs: [Any](https://docs.python.org/3/library/typing.html#typing.Any)) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)
