anesthetic.plotting package

Plotting public API.

class anesthetic.plotting.PlotAccessor(data)

Make plots of Series or DataFrame.

Uses the backend specified by the option plotting.backend. By default, matplotlib is used.

Parameters:

dataSeries or DataFrame

The object for which the method is called.

Attributes:

xlabel or position, default None

Only used if data is a DataFrame.

ylabel, position or list of label, positions, default None

Allows plotting of one column versus another. Only used if data is a DataFrame.

kindstr

The kind of plot to produce:

• ‘line’ : line plot (default)

• ‘bar’ : vertical bar plot

• ‘barh’ : horizontal bar plot

• ‘hist’ : histogram

• ‘box’ : boxplot

• ‘kde’ : Kernel Density Estimation plot

• ‘density’ : same as ‘kde’

• ‘area’ : area plot

• ‘pie’ : pie plot

• ‘scatter’ : scatter plot (DataFrame only)

• ‘hexbin’ : hexbin plot (DataFrame only)

• ‘hist_1d’ : 1d histogram

• ‘kde_1d’ : 1d Kernel Density Estimation plot

• ‘fastkde_1d’ : 1d Kernel Density Estimation plot with fastkde package

• ‘hist_2d’ : 2d histogram (DataFrame only)

• ‘kde_2d’ : 2d Kernel Density Estimation plot (DataFrame only)

• ‘fastkde_2d’ : 2d Kernel Density Estimation plot with fastkde package (DataFrame only)

• ‘scatter_2d’ : 2d scatter plot (DataFrame only)

axmatplotlib axes object, default None

An axes of the current figure.

subplotsbool or sequence of iterables, default False

Whether to group columns into subplots:

• False : No subplots will be used

• True : Make separate subplots for each column.

• sequence of iterables of column labels: Create a subplot for each group of columns. For example [(‘a’, ‘c’), (‘b’, ‘d’)] will create 2 subplots: one with columns ‘a’ and ‘c’, and one with columns ‘b’ and ‘d’. Remaining columns that aren’t specified will be plotted in additional subplots (one per column).

sharexbool, default True if ax is None else False

In case subplots=True, share x axis and set some x axis labels to invisible; defaults to True if ax is None otherwise False if an ax is passed in; Be aware, that passing in both an ax and sharex=True will alter all x axis labels for all axis in a figure.

shareybool, default False

In case subplots=True, share y axis and set some y axis labels to invisible.

layouttuple, optional

(rows, columns) for the layout of subplots.

figsizea tuple (width, height) in inches

Size of a figure object.

use_indexbool, default True

Use index as ticks for x axis.

titlestr or list

Title to use for the plot. If a string is passed, print the string at the top of the figure. If a list is passed and subplots is True, print each item in the list above the corresponding subplot.

gridbool, default None (matlab style default)

Axis grid lines.

legendbool or {‘reverse’}

Place legend on axis subplots.

stylelist or dict

The matplotlib line style per column.

logxbool or ‘sym’, default False

Use log scaling or symlog scaling on x axis.

logybool or ‘sym’ default False

Use log scaling or symlog scaling on y axis.

loglogbool or ‘sym’, default False

Use log scaling or symlog scaling on both x and y axes.

xtickssequence

Values to use for the xticks.

ytickssequence

Values to use for the yticks.

xlim2-tuple/list

Set the x limits of the current axes.

ylim2-tuple/list

Set the y limits of the current axes.

xlabellabel, optional

Name to use for the xlabel on x-axis. Default uses index name as xlabel, or the x-column name for planar plots.

Changed in version 2.0.0: Now applicable to histograms.

ylabellabel, optional

Name to use for the ylabel on y-axis. Default will show no ylabel, or the y-column name for planar plots.

Changed in version 2.0.0: Now applicable to histograms.

rotfloat, default None

Rotation for ticks (xticks for vertical, yticks for horizontal plots).

fontsizefloat, default None

Font size for xticks and yticks.

colormapstr or matplotlib colormap object, default None

Colormap to select colors from. If string, load colormap with that name from matplotlib.

colorbarbool, optional

If True, plot colorbar (only relevant for ‘scatter’ and ‘hexbin’ plots).

positionfloat

Specify relative alignments for bar plot layout. From 0 (left/bottom-end) to 1 (right/top-end). Default is 0.5 (center).

tablebool, Series or DataFrame, default False

If True, draw a table using the data in the DataFrame and the data will be transposed to meet matplotlib’s default layout. If a Series or DataFrame is passed, use passed data to draw a table.

yerrDataFrame, Series, array-like, dict and str

See Plotting with Error Bars for detail.

xerrDataFrame, Series, array-like, dict and str

Equivalent to yerr.

stackedbool, default False in line and bar plots, and True in area plot

If True, create stacked plot.

secondary_ybool or sequence, default False

Whether to plot on the secondary y-axis if a list/tuple, which columns to plot on secondary y-axis.

mark_rightbool, default True

When using a secondary_y axis, automatically mark the column labels with “(right)” in the legend.

include_boolbool, default is False

If True, boolean values can be plotted.

backendstr, default None

Backend to use instead of the backend specified in the option plotting.backend. For instance, ‘matplotlib’. Alternatively, to specify the plotting.backend for the whole session, set pd.options.plotting.backend.

**kwargs

Options to pass to matplotlib plotting method.

Returns:

matplotlib.axes.Axes or numpy.ndarray of them

If the backend is not the default matplotlib one, the return value will be the object returned by the backend.

fastkde_1d(**kwargs)

Plot a 1d marginalised distribution.

This functions as a wrapper around matplotlib.axes.Axes.plot(), with a kernel density estimation (KDE) computation provided by the package fastkde in-between. All remaining keyword arguments are passed onwards.

Parameters:

axmatplotlib.axes.Axes

Axis object to plot on.

datanp.array

Uniformly weighted samples to generate kernel density estimator.

xmin, xmaxfloat, default=None

lower/upper prior bound

levelslist

Values at which to draw iso-probability lines. Optional, Default: [0.95, 0.68]

qint or float or tuple, default=5

Quantile to determine the data range to be plotted.

• 0: full data range, i.e. q=0 –> quantile range (0, 1)

• int: q-sigma range, e.g. q=1 –> quantile range (0.16, 0.84)

• float: percentile, e.g. q=0.8 –> quantile range (0.1, 0.9)

• tuple: quantile range, e.g. (0.16, 0.84)

facecolorbool or string, default=False

If set to True then the 1d plot will be shaded with the value of the color kwarg. Set to a string such as ‘blue’, ‘k’, ‘r’, ‘C1’ ect. to define the color of the shading directly.

Returns:

linesmatplotlib.lines.Line2D

A list of line objects representing the plotted data (same as matplotlib.axes.Axes.plot() command).

See also

anesthetic.plot.fastkde_plot_1d()

fastkde_2d(x, y, **kwargs)

Plot a 2d marginalised distribution as contours.

This functions as a wrapper around matplotlib.axes.Axes.contour(), and matplotlib.axes.Axes.contourf() with a kernel density estimation (KDE) computation in-between. All remaining keyword arguments are passed onwards to both functions.

Parameters:

axmatplotlib.axes.Axes

Axis object to plot on.

data_x, data_ynp.array

The x and y coordinates of uniformly weighted samples to generate kernel density estimator.

levelslist

Amount of mass within each iso-probability contour. Has to be ordered from outermost to innermost contour. Default: [0.95, 0.68]

xmin, xmax, ymin, ymaxfloat, default=None

The lower/upper prior bounds in x/y coordinates.

Returns:

cmatplotlib.contour.QuadContourSet

A set of contourlines or filled regions.

See also

anesthetic.plot.fastkde_contour_plot_2d()

hist_1d(**kwargs)

Plot a 1d histogram.

This functions is a wrapper around matplotlib.axes.Axes.hist(). All remaining keyword arguments are passed onwards.

Parameters:

axmatplotlib.axes.Axes

Axis object to plot on.

datanp.array

Samples to generate histogram from

weightsnp.array, optional

Sample weights.

qint or float or tuple, default=5

Quantile to determine the data range to be plotted.

• 0: full data range, i.e. q=0 –> quantile range (0, 1)

• int: q-sigma range, e.g. q=1 –> quantile range (0.16, 0.84)

• float: percentile, e.g. q=0.8 –> quantile range (0.1, 0.9)

• tuple: quantile range, e.g. (0.16, 0.84)

Returns:

patcheslist or list of lists

Silent list of individual patches used to create the histogram or list of such list if multiple input datasets.

Other Parameters:

**kwargsmatplotlib.axes.Axes.hist() properties

See also

anesthetic.plot.hist_plot_1d()

hist_2d(x, y, **kwargs)

Plot a 2d marginalised distribution as a histogram.

This functions as a wrapper around matplotlib.axes.Axes.hist2d().

Parameters:

axmatplotlib.axes.Axes

Axis object to plot on.

data_x, data_ynp.array

The x and y coordinates of uniformly weighted samples to generate a two-dimensional histogram.

levelslist, default=None

Shade iso-probability contours containing these levels of probability mass. If None defaults to usual matplotlib.axes.Axes.hist2d() colouring.

qint or float or tuple, default=5

Quantile to determine the data range to be plotted.

• 0: full data range, i.e. q=0 –> quantile range (0, 1)

• int: q-sigma range, e.g. q=1 –> quantile range (0.16, 0.84)

• float: percentile, e.g. q=0.8 –> quantile range (0.1, 0.9)

• tuple: quantile range, e.g. (0.16, 0.84)

Returns:

cmatplotlib.collections.QuadMesh

A set of colors.

See also

anesthetic.plot.hist_plot_2d()

kde_1d(**kwargs)

Plot a 1d marginalised distribution.

This functions as a wrapper around matplotlib.axes.Axes.plot(), with a kernel density estimation computation provided by scipy.stats.gaussian_kde in-between. All remaining keyword arguments are passed onwards.

Parameters:

axmatplotlib.axes.Axes

Axis object to plot on.

datanp.array

Samples to generate kernel density estimator.

weightsnp.array, optional

Sample weights.

ncompressint, str, default=False

Degree of compression.

• If False: no compression.

• If True: compresses to the channel capacity, equivalent to ncompress='entropy'.

• If int: desired number of samples after compression.

• If str: determine number from the Huggins-Roy family of effective samples in anesthetic.utils.neff() with beta=ncompress.

nplot_1dint, default=100

Number of plotting points to use.

levelslist

Values at which to draw iso-probability lines. Default: [0.95, 0.68]

qint or float or tuple, default=5

Quantile to determine the data range to be plotted.

• 0: full data range, i.e. q=0 –> quantile range (0, 1)

• int: q-sigma range, e.g. q=1 –> quantile range (0.16, 0.84)

• float: percentile, e.g. q=0.8 –> quantile range (0.1, 0.9)

• tuple: quantile range, e.g. (0.16, 0.84)

facecolorbool or string, default=False

If set to True then the 1d plot will be shaded with the value of the color kwarg. Set to a string such as ‘blue’, ‘k’, ‘r’, ‘C1’ ect. to define the color of the shading directly.

bw_methodstr, scalar or callable, optional

Forwarded to scipy.stats.gaussian_kde.

bw_scalefloat, default=1

Scales the bandwidth relative to the automatically computed one by scipy.stats.gaussian_kde. A value greater 1 will smooth more, a value smaller 1 will smooth less.

betaint, float, default = 1

The value of beta used to calculate the number of effective samples

Returns:

linesmatplotlib.lines.Line2D

A list of line objects representing the plotted data (same as matplotlib.axes.Axes.plot() command).

See also

anesthetic.plot.kde_plot_1d()

kde_2d(x, y, **kwargs)

Plot a 2d marginalised distribution as contours.

This functions as a wrapper around matplotlib.axes.Axes.contour() and matplotlib.axes.Axes.contourf() with a kernel density estimation (KDE) computation provided by scipy.stats.gaussian_kde in-between. All remaining keyword arguments are passed onwards to both functions.

Parameters:

axmatplotlib.axes.Axes

Axis object to plot on.

data_x, data_ynp.array

The x and y coordinates of uniformly weighted samples to generate kernel density estimator.

weightsnp.array, optional

Sample weights.

levelslist, optional

Amount of mass within each iso-probability contour. Has to be ordered from outermost to innermost contour. Default: [0.95, 0.68]

ncompressint, str, default=’equal’

Degree of compression.

• If int: desired number of samples after compression.

• If False: no compression.

• If True: compresses to the channel capacity, equivalent to ncompress='entropy'.

• If str: determine number from the Huggins-Roy family of effective samples in anesthetic.utils.neff() with beta=ncompress.

nplot_2dint, default=1000

Number of plotting points to use.

bw_methodstr, scalar or callable, optional

Forwarded to scipy.stats.gaussian_kde.

bw_scalefloat, default=1

Scales the bandwidth relative to the automatically computed one by scipy.stats.gaussian_kde. A value greater 1 will smooth more, a value smaller 1 will smooth less.

Returns:

cmatplotlib.contour.QuadContourSet

A set of contourlines or filled regions.

See also

anesthetic.plot.kde_contour_plot_2d()

scatter_2d(x, y, **kwargs)

Plot samples from a 2d marginalised distribution.

This functions as a wrapper around matplotlib.axes.Axes.plot(), enforcing any prior bounds. All remaining keyword arguments are passed onwards.

Parameters:

axmatplotlib.axes.Axes

axis object to plot on

data_x, data_ynp.array

x and y coordinates of uniformly weighted samples to plot.

ncompressint, str, default=’equal’

Degree of compression.

• If int: desired number of samples after compression.

• If False: no compression.

• If True: compresses to the channel capacity, equivalent to ncompress='entropy'.

• If str: determine number from the Huggins-Roy family of effective samples in anesthetic.utils.neff() with beta=ncompress.

Returns:

linesmatplotlib.lines.Line2D

A list of line objects representing the plotted data (same as matplotlib.axes.Axes.plot() command).

See also

anesthetic.plot.scatter_plot_2d()