libics.tools.plot

libics.tools.plot.base.bar(*data, x=None, y=None, width=None, bar_orientation='vertical', xnorm=None, ynorm=None, linestyle='=', xlabel=True, ylabel=True, label=None, title=None, ax=None, **kwargs)

Generates a 1D bar plot.

See matplotlib API:

• https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.bar

Parameters

*dataarray-like, ArrayData, SeriesData

Plots data depending on passed data. Supports var data of ArrayData or SeriesData.

x, yarray-like, ArrayData, SeriesData

Explicitly given plot data for each axis. Overwrites *data.

widtharray-like, float

Width of the bars in units of the x variable.

bar_orientationstr

Orientation of individual bars: “vertical”, “horizontal”.

xnorm, ynormfloat, ValQuantity

Normalization value for plot data. If Quantity, sets an automatic label.

linestylestr

Matplotlib linestyle.

xlabel, ylabel, label, titlestr or bool

Labels for the various properties. If True, tries to automatically set a label.

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.barh(*args, bar_orientation='horizontal', **kwargs)

Wrapper for bar().

Defaults to horizontally instead of vertically oriented bars. Uses plt.barh instead of plt.bar nomenclature, e.g., inverted meaning of (width, height) or (x…, y…).

Generates a 1D bar plot.

See matplotlib API:

• https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.bar

Parameters

*dataarray-like, ArrayData, SeriesData

Plots data depending on passed data. Supports var data of ArrayData or SeriesData.

x, yarray-like, ArrayData, SeriesData

Explicitly given plot data for each axis. Overwrites *data.

widtharray-like, float

Width of the bars in units of the x variable.

bar_orientationstr

Orientation of individual bars: “vertical”, “horizontal”.

xnorm, ynormfloat, ValQuantity

Normalization value for plot data. If Quantity, sets an automatic label.

linestylestr

Matplotlib linestyle.

xlabel, ylabel, label, titlestr or bool

Labels for the various properties. If True, tries to automatically set a label.

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.contourf(*data, x=None, y=None, c=None, xnorm=None, ynorm=None, cnorm=None, vmin=None, vmax=None, vdif=None, vcen=None, xlabel=True, ylabel=True, title=None, colorbar=None, cb_orientation='vertical', clabel=True, aspect=None, ax=None, **kwargs)

Generates a 2D color contour plot.

Uses the contourf function. See matplotlib API: https://matplotlib.org/api/_as_gen/matplotlib.pyplot.contourf.html

Parameters

*dataarray-like, ArrayData, SeriesData

Plots data depending on passed data. Supports var data of ArrayData or SeriesData.

x, yarray-like, ArrayData, SeriesData

Explicitly given var plot data for each axis. Overwrites *data.

carray-like, ArrayData

Explicitly given color plot data. Overwrites *data.

xnorm, ynorm, cnormfloat, ValQuantity

Normalization value for plot data. If Quantity, sets an automatic label.

vmin, vmax, vdif, vcenfloat

Defines the color map range. Minimum/maximum are given either directly (vmin, vmax) or are deduced from center and range (vcen, vdif). If vdif is True, the full range is automatically assigned.

xlabel, ylabel, clabel, titlestr or bool

Labels for the various properties. If True, tries to automatically set a label.

colorbarbool or matplotlib.axes.Axes

Flag whether to show color bar. If bool, specifies the parent axes. If Axes, specifies the color bar axes.

cb_orientationstr

“horizontal”, “vertical”.

aspectfloat

Axes data scale aspect ratio.

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.pcolorim(*args, aspect=1, **kwargs)

Wrapper for pcolormesh().

Defaults to a common aspect ratio.

Generates a 2D color plot.

Uses the pcolormesh function. See matplotlib API: https://matplotlib.org/api/_as_gen/matplotlib.pyplot.pcolormesh.html

Parameters

*dataarray-like, ArrayData, SeriesData

Plots data depending on passed data. Supports var data of ArrayData or SeriesData.

x, yarray-like, ArrayData, SeriesData

Explicitly given var plot data for each axis. Overwrites *data.

carray-like, ArrayData

Explicitly given color plot data. Overwrites *data.

xnorm, ynorm, cnormfloat, ValQuantity

Normalization value for plot data. If Quantity, sets an automatic label.

vmin, vmax, vdif, vcenfloat

Defines the color map range. Minimum/maximum are given either directly (vmin, vmax) or are deduced from center and range (vcen, vdif). If vdif is True, the full range is automatically assigned.

xlabel, ylabel, clabel, titlestr or bool

Labels for the various properties. If True, tries to automatically set a label.

colorbarbool or matplotlib.axes.Axes

Flag whether to show color bar. If bool, specifies the parent axes. If Axes, specifies the color bar axes.

cb_orientationstr

“horizontal”, “vertical”.

cticksNone or list(ticks)

Colorbar ticks.

aspectfloat

Axes data scale aspect ratio.

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.pcolormesh(*data, x=None, y=None, c=None, xnorm=None, ynorm=None, cnorm=None, vmin=None, vmax=None, vdif=None, vcen=None, xlabel=True, ylabel=True, title=None, colorbar=None, cb_orientation='vertical', clabel=True, cticks=None, aspect=None, ax=None, **kwargs)

Generates a 2D color plot.

Uses the pcolormesh function. See matplotlib API: https://matplotlib.org/api/_as_gen/matplotlib.pyplot.pcolormesh.html

Parameters

*dataarray-like, ArrayData, SeriesData

Plots data depending on passed data. Supports var data of ArrayData or SeriesData.

x, yarray-like, ArrayData, SeriesData

Explicitly given var plot data for each axis. Overwrites *data.

carray-like, ArrayData

Explicitly given color plot data. Overwrites *data.

xnorm, ynorm, cnormfloat, ValQuantity

Normalization value for plot data. If Quantity, sets an automatic label.

vmin, vmax, vdif, vcenfloat

Defines the color map range. Minimum/maximum are given either directly (vmin, vmax) or are deduced from center and range (vcen, vdif). If vdif is True, the full range is automatically assigned.

xlabel, ylabel, clabel, titlestr or bool

Labels for the various properties. If True, tries to automatically set a label.

colorbarbool or matplotlib.axes.Axes

Flag whether to show color bar. If bool, specifies the parent axes. If Axes, specifies the color bar axes.

cb_orientationstr

“horizontal”, “vertical”.

cticksNone or list(ticks)

Colorbar ticks.

aspectfloat

Axes data scale aspect ratio.

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.plot(*data, x=None, y=None, xerr=None, yerr=None, xnorm=None, ynorm=None, marker=None, xlabel=True, ylabel=True, label=None, title=None, ax=None, **kwargs)

Generates a 1D plot.

Supports scatter plots, line plots and 2D error bars. See matplotlib API:

• https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.plot

• https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.errorbar

Parameters

*dataarray-like, ArrayData, SeriesData

Plots data depending on passed data. Supports var data of ArrayData or SeriesData.

x, y, xerr, yerrarray-like, ArrayData, SeriesData

Explicitly given plot data (or error) for each axis. Overwrites *data.

xnorm, ynormfloat, ValQuantity

Normalization value for plot data. If Quantity, sets an automatic label.

markerstr or object

Matplotlib markers. Using square brackets ([<marker>]) around the matplotlib marker creates a larger marker with a darker edge color. Shorthands: “O” == “[o]”.

xlabel, ylabel, label, titlestr or bool

Labels for the various properties. If True, tries to automatically set a label.

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.plot_ellipse(center=None, size=None, linestyle='=', angle=None, ax=None, **kwargs)

Plots an ellipse.

Parameters

center[float, float]

Center of ellipse, specified as [x, y].

sizefloat or [float, float]

Diameter of ellipse in both dimensions. If float, plots a circle.

anglefloat

Rotation of ellipse.

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.plot_polygon(vertices=None, center=None, size=None, num=None, linestyle='=', angle=None, ax=None, **kwargs)

Plots a regular or irregular polygon.

An irregular polygon can be directly specified by its vertices. A regular polygon can be specified by its center location, size, and `num`ber of vertices.

Parameters

verticesIter[[float], float]]

Vertex coordinates of (irregular) polygon, specified as [[x0, y0], [x1, y1], …]. Takes precedence over center, size and num.

center[float, float]

(Regular) polygon center, specified as [x, y].

sizefloat

Size (diameter) of polygon.

numint

Number of vertices of (regular) polygon.

anglefloat

Rotation of polygon (only applied to regular polygons).

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.plot_rectangle(rect=None, center=None, size=None, idx_rect=None, linestyle='=', angle=None, ax=None, **kwargs)

Plots a rectangle.

The rectangle can be specified either by its left-bottom and right-top corners (rect) or by its center location and size.

Parameters

rect[[float, float], [float, float]]

Rectangle corners, specified as [[xmin, xmax], [ymin, ymax]]. Takes precedence over center and size.

center, size[float, float]

Rectangle center and size, specified as [x, y].

idx_rect[[int, int], [int, int]] or tuple(slice)

Index rectangle specified as rect or as slice object. Applies an offset of -0.5 to account for being an index.

anglefloat

Rotation of rectangle.

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.remove_axes(*axs, enforce=False, on_empty=True)

(Conditionally) removes a matplotlib axes.

Parameters

*axsmatplotlib.axes.Axes

Matplotlib axes object.

enforcebool

Whether to remove the axes unconditionally.

on_emptybool

Whether to remove the axes if no artists are present.

libics.tools.plot.base.savefig(fp, *args, **kwargs)

libics.tools.plot.base.scatter(*args, marker='O', linestyle='None', **kwargs)

Wrapper for plot().

Defaults to markers instead of lines.

Generates a 1D plot.

Supports scatter plots, line plots and 2D error bars. See matplotlib API:

• https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.plot

• https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.errorbar

Parameters

*dataarray-like, ArrayData, SeriesData

Plots data depending on passed data. Supports var data of ArrayData or SeriesData.

x, y, xerr, yerrarray-like, ArrayData, SeriesData

Explicitly given plot data (or error) for each axis. Overwrites *data.

xnorm, ynormfloat, ValQuantity

Normalization value for plot data. If Quantity, sets an automatic label.

markerstr or object

Matplotlib markers. Using square brackets ([<marker>]) around the matplotlib marker creates a larger marker with a darker edge color. Shorthands: “O” == “[o]”.

xlabel, ylabel, label, titlestr or bool

Labels for the various properties. If True, tries to automatically set a label.

axmatplotlib.axes.Axes

Matplotlib axes.

**kwargs

Keyword arguments passed to the plot function.

libics.tools.plot.base.style_axes(ax=None, xmin=None, xmax=None, ymin=None, ymax=None, xlabel=None, ylabel=None, title=None, aspect=None, grid=None, legend=None, minorticks=None, **ticks)

Styles axes properties.

See matplotlib API: https://matplotlib.org/api/axes_api.html.

Parameters

axmatplotlib.axes.Axes

Matplotlib axes.

xmin, xmax, ymin, ymaxfloat

Axes limits.

xlabel, ylabel, titlestr

Axes labels.

aspectfloat

Axes data scale aspect ratio.

gridbool or str

True, False, “major”, “minor”, “both”.

legendbool

Parameter passed to legend call.

minorticksbool

Whether to show minor ticks.

**ticks

See tick_params().

libics.tools.plot.base.style_figure(fig=None, ax_style=None, figsize=None, figsize_unit='in', dpi=None, tight_layout=None, edgecolor=None, facecolor=None, title=None)

Styles figure and contained axes properties.

See matplotlib API: https://matplotlib.org/api/_as_gen/matplotlib.figure.Figure.html.

Parameters

figmatplotlib.figure.Figure

Matplotlib figure.

ax_styledict

Keyword arguments for style_axes(). Is applied to all axes contained in the figure.

figsize_unitstr

“in”, “mm”. Unit used to interpret the figsize argument.

dpifloat

Figure resolution in dots per inch (dpi).

tight_layoutbool or dict

See matplotlib.figure.Figure.set_tight_layout().

edgecolor, facecolorcolor

Edge, face color of the figure rectangle.

titlestr

Figure suptitle.

libics.tools.plot.base.subplots(fig=None, figsize=None, axsize=None, axsize_offset=None, dpi=None, size_unit='in', nrows=1, ncols=1, **kwargs)

Create a figure and a set of subplots.

See matplotlib API: https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.subplots.html.

libics.tools.plot.base.tick_params(ax=None, axis='both', capstyle=None, **kwargs)

Styles tick properties.

See matplotlib API: https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.tick_params.

Parameters

axmatplotlib.axes.Axes

Matplotlib axes.

axisstr

“both”, “x”, “y”.

capstylestr

“projecting”, “round”, “butt”.

**kwargs

See matplotlib.axes.Axes.tick_params().

libics.tools.plot.base.unsqueeze_axes(axs, ax_1d='col')

Unsqueezes multiple matplotlib axes to an array[row, col].

Parameters

axsIter[matplotlib.axes.Axes]

Collection of matplotlib axes.

ax_1dstr

If axs is 1D, it is assumed that the array dimension is “col” or “row”.

Returns

axsnp.ndarray(2, matplotlib.axes.Axes)

2D array of matplotlib axes. Dimensions: [row, col].

libics.tools.plot.base.use_style(name='libics')

Sets a matplotlib plot style.

Parameters

namestr

Matplotlib style file name.

colors

libics.tools.plot.colors.add_named_cmap(cmap, name=None, **kwargs)

Add a named color map to matplotlib.

libics.tools.plot.colors.add_named_color(name, color)

Add a named RGB(A) color to matplotlib.

libics.tools.plot.colors.change_brightness_rgb(rgb, scale)

Scales the brightness of a RGB color in HLS space.

libics.tools.plot.colors.darken_rgb(*rgbs, scale=0.5)

libics.tools.plot.colors.get_color_from_cmap(cmap, scale=0)

Gets a color at the position scale (within [0, 1]) from a colormap.

libics.tools.plot.colors.get_colors_from_cmap(cmap, num=6)

Gets discrete colors from a colormap.

libics.tools.plot.colors.get_srgb_black_tinted(rgb_color_ref)

libics.tools.plot.colors.get_srgb_gray_tinted(color, *args, cv_out=None, **kwargs)

Returns a grayscale sRGB color with infinitesimal chroma.

Can be used to construct single-hue color interpolation. If pure grayscales would be used, a hue of 0° would be used.

Parameters

rgb_color_refArray[n_color, float]

RGB color defining the hue.

grayscalefloat

Grayscale (clipped to the range [0.02, 0.98]). 0 corresponds to fully black, 1 to fully white.

libics.tools.plot.colors.get_srgb_grey_tinted(color, *args, cv_out=None, **kwargs)

Returns a grayscale sRGB color with infinitesimal chroma.

Can be used to construct single-hue color interpolation. If pure grayscales would be used, a hue of 0° would be used.

Parameters

rgb_color_refArray[n_color, float]

RGB color defining the hue.

grayscalefloat

Grayscale (clipped to the range [0.02, 0.98]). 0 corresponds to fully black, 1 to fully white.

libics.tools.plot.colors.get_srgb_linspace(*colors, cv_out=None, **kwargs)

Returns an array of interpolated sRGB colors.

Parameters

*keycolorsArray[n_colors, float]

Keycolors as sRGB values.

numint, optional

Number of interpolation points.

keycolor_distancesNone or Array[1, float], optional

Relative distances between the keycolors.

distance_measurestr, optional

“deltaE”: Scales keycolor_distances by the distance in JCh space. “index”: Does not scale keycolor_distances.

hue_polaritystr or None

As the hue is periodic, the interpolation can be performed “clockwise” or “anticlockwise”. If None, uses the polarity of the minimum hue distance.

Returns

rgb_interpolated_colorsnp.ndarray(2, float)

Interpolated sRGB colors with dimensions: [num, n_colors]

libics.tools.plot.colors.get_srgb_range(color, *args, cv_out=None, **kwargs)

Gets the smallest and largest value along a color dimension.

Parameters

rgb_colorArray[n_colors, float]

Reference sRGB color.

color_dimstr, optional

Color space dimension along which to return range: “lightness”, “chroma”, “saturation”

Returns

rgb_min, rgb_maxtuple(np.ndarray(n_colors, float))

Minimum and maximum sRGB colors.

libics.tools.plot.colors.get_srgb_white_tinted(rgb_color_ref)

libics.tools.plot.colors.hex_to_rgb(hex)

libics.tools.plot.colors.hls_to_rgb(hls)

Converts a HLS color to a RGB color.

libics.tools.plot.colors.hsv_to_rgb(hsv)

Converts a HSV color to a RGB color.

libics.tools.plot.colors.interpolate_rgb(rgb1, rgb2, scale=0.5)

Interpolates linearly between two RGB colors in HLS space.

Parameters

rgb1, rgb2

RGB colors.

scalefloat

Relative interpolation position between the two colors, where (0, 1) corresponds to (rgb1, rgb2).

libics.tools.plot.colors.jch_to_rgb(*colors, cv_out=None, **kwargs)

Converts a RGB-style color to a JCh color.

libics.tools.plot.colors.lighten_rgb(*rgbs, scale=2)

libics.tools.plot.colors.make_cmap(colors, name=None, continuous=True)

Creates a matplotlib continuous or discrete colormap.

libics.tools.plot.colors.normalize(ar, vmin=None, vmax=None)

Normalizes an array linearly onto the [0, 1] interval.

Parameters

arnp.ndarray(float)

Array-like to be normalized.

vmin, vmaxfloat

Normalization interval on the current scale. If None, uses the array minimum and maximum, respectively. If vmin equals vmax, a zero-array is returned.

Returns

normnp.ndarray(float)

Normalized array.

libics.tools.plot.colors.parse_color(*colors, cv_out=None, **kwargs)

Parses color strings or hex codes to color values.

libics.tools.plot.colors.rgb_blacken(color, *args, cv_out=None, **kwargs)

Blackens a sRGB color by a given scale.

Parameters

scalefloat, optional

1 corresponds to fully black.

libics.tools.plot.colors.rgb_change_brightness(color, *args, cv_out=None, **kwargs)

Changes the saturation of an sRGB color.

Parameters

rgb_colorArray[n_colors, float]

sRGB color to change.

brightness_changefloat

Additive change of brightness.

scalestr, optional

Interprets brightness_change as follows: “rel”: relative to the in-gamut range: [0, 1]. “abs”: as absolute value in JCh color space: [0, 100].

clip_jchbool, optional

If the change results in an out-of-gamut color, whether to clip in JCh space instead of sRGB space.

Returns

rgb_colornp.ndarray(n_colors, float)

Changed sRGB color.

libics.tools.plot.colors.rgb_change_chroma(color, *args, cv_out=None, **kwargs)

Changes the chroma of an sRGB color.

Parameters

rgb_colorArray[n_colors, float]

sRGB color to change.

chroma_changefloat

Additive change of chroma.

scalestr, optional

Interprets chroma_change as follows: “rel”: relative to the in-gamut range. “abs”: as absolute value in JCh color space.

clip_jchbool, optional

If the change results in an out-of-gamut color, whether to clip in JCh space instead of sRGB space.

Returns

rgb_colornp.ndarray(n_colors, float)

Changed sRGB color.

libics.tools.plot.colors.rgb_change_lightness(color, *args, cv_out=None, **kwargs)

Changes the lightness of an sRGB color.

Parameters

rgb_colorArray[n_colors, float]

sRGB color to change.

lightness_changefloat

Additive change of lightness.

scalestr, optional

Interprets lightness_change as follows: “rel”: relative to the in-gamut range. “abs”: as absolute value in JCh color space.

clip_jchbool, optional

If the change results in an out-of-gamut color, whether to clip in JCh space instead of sRGB space.

Returns

rgb_colornp.ndarray(n_colors, float)

Changed sRGB color.

libics.tools.plot.colors.rgb_change_saturation(color, *args, cv_out=None, **kwargs)

Changes the saturation of an sRGB color.

Parameters

rgb_colorArray[n_colors, float]

sRGB color to change.

saturation_changefloat

Additive change of lightness.

scalestr, optional

Interprets lightness_change as follows: “rel”: relative to the in-gamut range: [0, 1]. “abs”: as absolute value in JCh color space: [0°, 90°].

clip_jchbool, optional

If the change results in an out-of-gamut color, whether to clip in JCh space instead of sRGB space.

Returns

rgb_colornp.ndarray(n_colors, float)

Changed sRGB color.

libics.tools.plot.colors.rgb_equalize_lightness(*colors, cv_out=None, **kwargs)

Returns the RGB colors with equalized lightness, preserving saturation.

Parameters

trg_lightnessfloat or None or sRGB color

Target lightness in JCh color space (in range [0, 100]). If None, chooses a common lightness trying to preserve lightness of given colors. If sRGB color, uses its lightness as target.

clip_jchbool`

Whether to clip in JCh space (reduces chroma to fit in sRGB gamut).

libics.tools.plot.colors.rgb_to_hex(*rgb_colors)

Converts a RGB-style color to a hex string.

libics.tools.plot.colors.rgb_to_hls(*colors, cv_out=None, **kwargs)

Converts a RGB-style color to a HLS color.

libics.tools.plot.colors.rgb_to_hsv(*colors, cv_out=None, **kwargs)

Converts a RGB-style color to a HSV color.

libics.tools.plot.colors.rgb_to_jch(*colors, cv_out=None, **kwargs)

Converts a RGB-style color to a JCh color.

libics.tools.plot.colors.rgb_whiten(color, *args, cv_out=None, **kwargs)

Whitens a sRGB color by a given scale.

Parameters

scalefloat, optional

1 corresponds to fully white.

libics.tools.plot.colors.set_color_cycle(colors)

Change the matplotlib default color cycle to the given colors.

layout

class libics.tools.plot.layout.SubfigLayout(**kwargs)

Bases: object

Matplotlib fixed layout class.

Can be used to layout nested axes in a figure with exact positioning.

Parameters

figmpl.figure.Figure

Matplotlib figure.

subfig_rect(float, float, float, float)

Subfigure rectangle.

left, right, top, bottomfloat

Subfigure outside margins in mm.

hcenter, vcenterfloat or Iter[float]

Horizontal and vertical margins between sublayouts in mm. If float, applies the same margin between all sublayouts.

sublayoutsIter[2, (SubfigLayout or True)]

2D grid of sublayouts. Can be another SubfigLayout or a mpl.axes.Axes object (if True, creates an axes).

sublayout_widths, sublayout_heightsIter[1, SubfigSize]

Widths and heights of the sublayouts.

Attributes

figsize

ncols

nrows

shape

subfig_rect

sublayout_heights

sublayout_widths

sublayouts

Methods

cv_center_to_rect(mpl_center)	Converts a matplotlib center to rectangle.
cv_rect_to_center(mpl_rect)	Converts a matplotlib rectangle to center.
get_sublayout_rect([row, col, subfig_rect])	Gets the position and size of a sublayout.
get_sublayout_size(subfig_size[, row, col])	Calculates the sublayout size.
iter_axs()	Gets an iterator over all sublayout axes.
make_ax([row, col, subfig_rect])	Creates a matplotlib axes at the given sublayout position.

normalize_rect

LOGGER = <Logger libics.tools.plot.layout.SubfigLayout (WARNING)>

static cv_center_to_rect(mpl_center)

Converts a matplotlib center to rectangle.

Dimensions: […, (xcenter, ycenter, width, height)] -> […, (left, bottom, width, height)]

static cv_rect_to_center(mpl_rect)

Converts a matplotlib rectangle to center.

Dimensions: […, (left, bottom, width, height)] -> […, (xcenter, ycenter, width, height)]

property figsize

get_sublayout_rect(row=None, col=None, subfig_rect=None)

Gets the position and size of a sublayout.

Parameters

row, colint or slice or None

Row/column indices of the requested sublayout. If int, returns a single rect (along resp. dim.). If slice, returns a single rect (along resp. dim.) spanning the sliced range. If None, returns a list of rects.

subfig_rectIter[float] or None

Subfigure rectangle. If None, uses internal variable.

Returns

rectsnp.ndarray(float)

Rectangle parameters (left, bottom, width, height) of the requested sublayout in mm. May have more dimensions […, 4] if multiple rows/columns are requested.

get_sublayout_size(subfig_size, row=None, col=None)

Calculates the sublayout size.

Parameters

subfig_size(float, float)

Size of full subfigure.

row, colint or None

Sublayout indices for which to calculate size. If None, returns sizes of all sublayouts.

Returns

widths, heightsfloat or np.ndarray(1, float)

Width and height of selected sublayout(s).

iter_axs()

Gets an iterator over all sublayout axes.

Creates the axes if not yet created.

make_ax(row=None, col=None, subfig_rect=None)

Creates a matplotlib axes at the given sublayout position.

Checks if the sublayout axes was already created. Creates only axes if the sublayout item is True.

Parameters

row, colint or None

Sublayout indices to create an axes in. If None, creates an axes for each sublayout item.

subfig_rectIter[float] or None

Subfigure rectangle. If None, uses internal variable.

Returns

axmpl.axes.Axes

Created matplotlib axes. Is vectorial if multiple rows/columns were selected.

property ncols

normalize_rect(rect_mm)

property nrows

property shape

property subfig_rect

property sublayout_heights

property sublayout_widths

property sublayouts

class libics.tools.plot.layout.SubfigMargins(**kwargs)

Bases: object

Helper class for subfigure layout margins along one dimension.

Implements the __getitem__ method to index margins, where [0] indexes the lower (outer) margin and [1:] indexes the inner margins.

Parameters

low, highfloat

Margins on the lower and upper bounds in mm.

centerfloat or Iter[float]

Margins between sublayouts in mm.

Attributes

left, bottom, right topfloat

Aliases for low and high.

outer, innerfloat

Used to overwrite all outer/inner margins.

Methods

get_outer_margin_size()	Gets the sum of the outer margins.
get_total_margin_size([num])	Gets the sum of all margins assuming num sublayouts.

property center

get_outer_margin_size()

Gets the sum of the outer margins.

get_total_margin_size(num=None)

Gets the sum of all margins assuming num sublayouts.

class libics.tools.plot.layout.SubfigSize(size=1, rel=True)

Bases: object

Helper class representing a scalar size.

Is used to distinguish between a relative or absolute size.

Parameters

sizefloat

Size value.

relbool

Whether size is interpreted as relative quantity.

Methods

is_fixed
is_relative

is_fixed()

is_relative()

libics.tools.plot.layout.make_fixed_axes(fig, rect, **kwargs)

Creates a matplotlib axes at a fixed position.

Parameters

figmatplotlib.figure.Figure

Figure to create the axes in.

rectIter[float]

Axes rectangle (left, bottom, width, height) in units relative to the figure size.

**kwargs

Keyword arguments passed to matplotlib.Figure.add_axes.

Returns

axmatplotlib.axes.Axes

Created axes.

multi

Module providing multi-axes plots of higher-dimensional data.

libics.tools.plot.multi.plot_ax_array(dataset, plot_func, x_key=None, arg_keys=None, kwarg_keys=None, select_keys=None, fig=None, axs=None, sharex=False, sharey=False, remove_empty=True, figsize=None, axsize=None, axsize_offset=(0.2, 0.2), dpi=None, size_unit='in', share_list=None, quantitative_list=None, fmt_keys=None, **plt_params)

Plots a data set into a matplotlib axes array.

Different data dimensions can be encoded in the plot style.

Parameters

datasetpd.DataFrame or dict(str->list)

Data set.

plot_funccallable

Plot function. Must accept parameter ax as matplotlib axes.

x_keystr

If provided, the plot call is altered. After filtering the data set according to select_keys, plot_func is called as: plot_func(dataset[x_key], dataset[arg_keys[0]], …)

arg_keysIter[str]

List of data keys used to call plot_func. Call signature: plot_func(dataset_row[arg_key[0]], …).

kwarg_keysdict(str->str)

Dictionary mapping keyword to data keys used to call plot_func. Call signature for key->val: plot_func(…, key=dataset_row[val], …).

select_keysdict(str->Iter[str])

Chooses how the data should be encoded as plot styles. Dictionary mapping plot style to data keys, e.g., {“color”: [“data_column0”, “data_column1”]}.

fig, axs

Matplotlib figure or axes into which to plot data. If None, is automatically generated.

sharex, shareybool

Whether to share axes ticks.

remove_emptybool

Whether to remove empty matplotlib axes.

fig_size, ax_size, axsize_offset, size_unit, dpi

Figure size if fig is automatically generated.

share_listIter[str] or None

List of plot keys which should have common representation across axes.

quantitative_listIter[str] or None

List of plot keys to be used quantitatively.

fmt_keysdict(str->str or True)

Formatting string by plot key. Use “{0}, {1}, …” to select the argument as ordered in select_keys.

**plt_paramsstr->Any or str->Iter[Any]

Keyword arguments for plot keys, e.g., color=”red”. If the plot key is selected for data differentiation, append an s, e.g., colors=[“red”, “green”, “blue”].

Returns

axsnp.ndarray(2, matplotlib.axes.Axes)

Matplotlib axes array.

Examples

Simple example for plotting two rows of 1D plots with different colors:

>>> dataset = DataSequence({
...     "x": np.arange(10),
...     "y": np.linspace(-1, 1, num=10),
...     "z": 5*["a"] + 5*["b"],
...     "a": 5*[True] + 3*[False] + 2*[True],
... })
>>> arg_keys = ["y"]
>>> select_keys = {"color": "a", "label": "a", "row": "z"}
>>> share_list = []
>>> fmt_keys = {"label": r"a = {0}"}
>>> x_key = "x"
>>> axs = plot.plot_ax_array(
...     dataset, plot.scatter,
...     x_key=x_key, arg_keys=arg_keys,
...     select_keys=select_keys,
...     share_list=share_list, fmt_keys=fmt_keys,
...     axsize=(5, 3.5)
... )
>>> for ax in np.ravel(axs):
...     plot.style_axes(ax=ax, legend=True)
>>> plot.show()