interplot Documentation and API reference

Create matplotlib/plotly hybrid plots with a few lines of code.

It combines the best of the matplotlib and the plotly worlds through a unified, flat API. All the necessary boilerplate code is contained in this module.

Currently supported:

• line plots (scatter)

• line fills

• histograms

• heatmaps

• boxplot

• linear regression

• text annotations

• 2D subplots

• color cycling

The core Plot class

class interplot.Plot(interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xlog=False, ylog=False, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None)

Bases: NotebookInteraction

Create matplotlib/plotly hybrid plots with a few lines of code.

It combines the best of the matplotlib and the plotly worlds through a unified, flat API. All the necessary boilerplate code is contained in this module.

Currently supported:

• line plots (scatter)

• line fills

• histograms

• heatmaps

• boxplot

• linear regression

• text annotations

• 2D subplots

• color cycling

Parameters:

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

Examples

>>> fig = interplot.Plot(
...     interactive=True,
...     title="Everything Under Control",
...     fig_size=(800, 500),
...     rows=1,
...     cols=2,
...     shared_yaxes=True,
...     save_fig=True,
...     save_format=("html", "png"),
...     # ...
... )
... fig.add_hist(np.random.normal(1, 0.5, 1000), row=0, col=0)
... fig.add_boxplot(
...     [
...         np.random.normal(20, 5, 1000),
...         np.random.normal(40, 8, 1000),
...         np.random.normal(60, 5, 1000),
...     ],
...     row=0,
...     col=1,
... )
... # ...
... fig.post_process()
... fig.show()
saved figure at Everything-Under-Control.html
saved figure at Everything-Under-Control.png

Methods

__call__(*args, **kwargs)	Calls the self.show() or self.plot() method.
add_bar(x[, y, horizontal, width, label, ...])	Draw a bar plot.
add_boxplot(x[, horizontal, label, ...])	Draw a boxplot.
add_fill(x, y1[, y2, label, show_legend, ...])	Draw a fill between two y lines.
add_heatmap(data[, lim, aspect, invert_x, ...])	Draw a heatmap.
add_hist([x, y, bins, density, label, ...])	Draw a histogram.
add_line(x[, y, x_error, y_error, mode, ...])	Draw a line or scatter plot.
add_linescatter(x[, y, x_error, y_error, ...])	Draw a line or scatter plot.
add_regression(x[, y, p, linspace])	Draw a linear regression plot.
add_scatter(x[, y, x_error, y_error, mode, ...])	Draw a line or scatter plot.
add_text(x, y, text[, horizontal_alignment, ...])	Draw text.
close()	Close the plot.
digest_color([color, alpha, increment])	Parse color with matplotlib.colors to a rgba array.
digest_marker(marker, mode, interactive[, ...])	Digests the marker parameter based on the given mode.
get_cycle_color([increment, i])	Retrieves the next color in the color cycle.
init([fig])	Initialize a Plot instance, if not already initialized.
post_process([global_custom_func, ...])	Finish the plot.
save(path[, export_format, print_confirm])	Save the plot.
show()	Show the plot.

static init(fig=None, *args, **kwargs)

Initialize a Plot instance, if not already initialized.

Parameters:

fig: Plot or any

If fig is a Plot instance, return it. Otherwise, create a new Plot instance.

*args, **kwargs: any

Passed to Plot.__init__.

get_cycle_color(increment=1, i=None)

Retrieves the next color in the color cycle.

Parameters:

increment: int, optional

If the same color should be returned the next time, pass 0. To jump the next color, pass 2. Default: 1

i: int, optional

Get a fixed index of the color cycle instead of the next one. This will not modify the regular color cycle iteration.

Returns:

color: str

HEX color, with leading hashtag

digest_color(color=None, alpha=None, increment=1)

Parse color with matplotlib.colors to a rgba array.

Parameters:

color: any color format matplotlib accepts, optional

E.g. “blue”, “#0000ff”, “C3” If None is provided, the next one from COLOR_CYCLE will be picked.

alpha: float, optional

Set alpha / opacity. Overrides alpha contained in color input. Default: None (use the value contained in color or default to 1)

increment: int, optional

If a color from the cycler is picked, increase the cycler by this increment.

static digest_marker(marker, mode, interactive, recursive=False, **pty_marker_kwargs)

Digests the marker parameter based on the given mode.

Parameters:

marker: int or str

The marker to be digested. If an integer is provided, it is converted to the corresponding string marker using plotly numbering. If not provided, the default marker “circle” is used.

mode: str

The mode to determine if markers should be used. If no markers should be drawn, None is returned.

Returns:

str or None

The digested marker string if markers are requested, otherwise None.

add_line(x, y=None, x_error=None, y_error=None, mode=None, line_style='solid', marker=None, marker_size=None, marker_line_width=1, marker_line_color=None, label=None, show_legend=None, color=None, opacity=None, linewidth=None, row=0, col=0, _serial_i=0, _serial_n=1, pty_marker_kwargs=None, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw a line or scatter plot.

Parameters:

x: array-like

y: array-like, optional

If only x is defined, it will be assumed as y. If a pandas Series is provided, the index will be taken as x. Else if a pandas DataFrame is provided, the method call is looped for each column. Else x will be an increment, starting from 0. If a 2D numpy array is provided, the method call is looped for each column.

x_error, y_error: number or shape(N,) or shape(2, N), optional

The errorbar sizes (matplotlib style):

• scalar: Symmetric +/- values for all data points.

• shape(N,): Symmetric +/-values for each data point.

• shape(2, N): Separate - and + values for each bar. First row

  contains the lower errors, the second row contains the upper errors.

• None: No errorbar.

mode: str, optional

Options: lines / lines+markers / markers

The default depends on the method called:

• add_line: lines

• add_scatter: markers

• add_linescatter: lines+markers

line_style: str, optional

Line style. Options: solid, dashed, dotted, dashdot

Aliases: -, –, dash, :, dot, -.

marker: int or str, optional

Marker style. If an integer is provided, it will be converted to the corresponding string marker using plotly numbering. If not provided, the default marker circle is used.

marker_size: int, optional

marker_line_width: int, optional

marker_line_color: str, optional

Can be hex, rgb(a) or any named color that is understood by matplotlib.

Default: same color as color.

label: str, optional

Trace label for legend.

show_legend: bool, optional

Whether to show the label in the legend.

By default, it will be shown if a label is defined.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

pty_marker_kwargs: dict, optional

PLOTLY ONLY.

Additional marker arguments.

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

Examples

Using the interplot.Plot method:

>>> fig = interplot.Plot(title="line, linescatter and scatter")
... fig.add_line([0,4,6,7], [1,2,4,8])
... fig.add_linescatter([0,4,6,7], [8,4,2,1])
... fig.add_scatter([0,4,6,7], [2,4,4,2], )
... fig.post_process()
... fig.show()

[plotly figure, “line, linescatter and scatter”]

Using interplot.line:

>>> interplot.line([0,4,6,7], [1,2,4,8])

>>> interplot.line(
...     x=[0,4,6,7],
...     y=[1,2,4,8],
...     interactive=False,
...     color="red",
...     title="matplotlib static figure",
...     xlabel="abscissa",
...     ylabel="ordinate",
... )

add_scatter(x, y=None, x_error=None, y_error=None, mode=None, line_style='solid', marker=None, marker_size=None, marker_line_width=1, marker_line_color=None, label=None, show_legend=None, color=None, opacity=None, linewidth=None, row=0, col=0, _serial_i=0, _serial_n=1, pty_marker_kwargs=None, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw a line or scatter plot.

Parameters:

x: array-like

y: array-like, optional

If only x is defined, it will be assumed as y. If a pandas Series is provided, the index will be taken as x. Else if a pandas DataFrame is provided, the method call is looped for each column. Else x will be an increment, starting from 0. If a 2D numpy array is provided, the method call is looped for each column.

x_error, y_error: number or shape(N,) or shape(2, N), optional

The errorbar sizes (matplotlib style):

• scalar: Symmetric +/- values for all data points.

• shape(N,): Symmetric +/-values for each data point.

• shape(2, N): Separate - and + values for each bar. First row

  contains the lower errors, the second row contains the upper errors.

• None: No errorbar.

mode: str, optional

Options: lines / lines+markers / markers

The default depends on the method called:

• add_line: lines

• add_scatter: markers

• add_linescatter: lines+markers

line_style: str, optional

Line style. Options: solid, dashed, dotted, dashdot

Aliases: -, –, dash, :, dot, -.

marker: int or str, optional

Marker style. If an integer is provided, it will be converted to the corresponding string marker using plotly numbering. If not provided, the default marker circle is used.

marker_size: int, optional

marker_line_width: int, optional

marker_line_color: str, optional

Can be hex, rgb(a) or any named color that is understood by matplotlib.

Default: same color as color.

label: str, optional

Trace label for legend.

show_legend: bool, optional

Whether to show the label in the legend.

By default, it will be shown if a label is defined.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

pty_marker_kwargs: dict, optional

PLOTLY ONLY.

Additional marker arguments.

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

Examples

Using the interplot.Plot method:

>>> fig = interplot.Plot(title="line, linescatter and scatter")
... fig.add_line([0,4,6,7], [1,2,4,8])
... fig.add_linescatter([0,4,6,7], [8,4,2,1])
... fig.add_scatter([0,4,6,7], [2,4,4,2], )
... fig.post_process()
... fig.show()

[plotly figure, “line, linescatter and scatter”]

Using interplot.line:

>>> interplot.line([0,4,6,7], [1,2,4,8])

>>> interplot.line(
...     x=[0,4,6,7],
...     y=[1,2,4,8],
...     interactive=False,
...     color="red",
...     title="matplotlib static figure",
...     xlabel="abscissa",
...     ylabel="ordinate",
... )

add_linescatter(x, y=None, x_error=None, y_error=None, mode=None, line_style='solid', marker=None, marker_size=None, marker_line_width=1, marker_line_color=None, label=None, show_legend=None, color=None, opacity=None, linewidth=None, row=0, col=0, _serial_i=0, _serial_n=1, pty_marker_kwargs=None, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw a line or scatter plot.

Parameters:

x: array-like

y: array-like, optional

If only x is defined, it will be assumed as y. If a pandas Series is provided, the index will be taken as x. Else if a pandas DataFrame is provided, the method call is looped for each column. Else x will be an increment, starting from 0. If a 2D numpy array is provided, the method call is looped for each column.

x_error, y_error: number or shape(N,) or shape(2, N), optional

The errorbar sizes (matplotlib style):

• scalar: Symmetric +/- values for all data points.

• shape(N,): Symmetric +/-values for each data point.

• shape(2, N): Separate - and + values for each bar. First row

  contains the lower errors, the second row contains the upper errors.

• None: No errorbar.

mode: str, optional

Options: lines / lines+markers / markers

The default depends on the method called:

• add_line: lines

• add_scatter: markers

• add_linescatter: lines+markers

line_style: str, optional

Line style. Options: solid, dashed, dotted, dashdot

Aliases: -, –, dash, :, dot, -.

marker: int or str, optional

Marker style. If an integer is provided, it will be converted to the corresponding string marker using plotly numbering. If not provided, the default marker circle is used.

marker_size: int, optional

marker_line_width: int, optional

marker_line_color: str, optional

Can be hex, rgb(a) or any named color that is understood by matplotlib.

Default: same color as color.

label: str, optional

Trace label for legend.

show_legend: bool, optional

Whether to show the label in the legend.

By default, it will be shown if a label is defined.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

pty_marker_kwargs: dict, optional

PLOTLY ONLY.

Additional marker arguments.

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

Examples

Using the interplot.Plot method:

>>> fig = interplot.Plot(title="line, linescatter and scatter")
... fig.add_line([0,4,6,7], [1,2,4,8])
... fig.add_linescatter([0,4,6,7], [8,4,2,1])
... fig.add_scatter([0,4,6,7], [2,4,4,2], )
... fig.post_process()
... fig.show()

[plotly figure, “line, linescatter and scatter”]

Using interplot.line:

>>> interplot.line([0,4,6,7], [1,2,4,8])

>>> interplot.line(
...     x=[0,4,6,7],
...     y=[1,2,4,8],
...     interactive=False,
...     color="red",
...     title="matplotlib static figure",
...     xlabel="abscissa",
...     ylabel="ordinate",
... )

add_bar(x, y=None, horizontal=False, width=0.8, label=None, show_legend=None, color=None, opacity=None, line_width=1, line_color=None, row=0, col=0, _serial_i=0, _serial_n=1, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw a bar plot.

Parameters:

x: array-like

y: array-like, optional

If only either x or y is defined, it will be assumed as the size of the bar, regardless whether it’s horizontal or vertical. If both x and y are defined, x will be taken as the position of the bar, and y as the size, regardless of the orientation. If a pandas Series is provided, the index will be taken as the position. Else if a pandas DataFrame is provided, the method call is looped for each column. If a 2D numpy array is provided, the method call is looped for each column, with the index as the position.

horizontal: bool, optional

If True, the bars are drawn horizontally. Default is False.

width: float, optional

Relative width of the bar. Must be in the range (0, 1).

label: str, optional

Trace label for legend.

show_legend: bool, optional

Whether to show the label in the legend.

By default, it will be shown if a label is defined.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

line_width: float, optional

The width of the bar outline. Default is 1.

line_color: str, optional

The color of the bar outline. This can be a named color or a tuple specifying the RGB values.

By default, the same color as the fill is used.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

add_hist(x=None, y=None, bins=None, density=False, label=None, show_legend=None, color=None, opacity=None, row=0, col=0, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw a histogram.

Parameters:

x: array-like

Histogram data.

bins: int, optional

Number of bins. If undefined, plotly/matplotlib will detect automatically. Default: None

label: str, optional

Trace label for legend.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, default: 0

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the hist core method.

add_boxplot(x, horizontal=False, label=None, show_legend=None, color=None, color_median='black', opacity=None, notch=True, row=0, col=0, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw a boxplot.

Parameters:

x: array or sequence of vectors

Data to build boxplot from.

horizontal: bool, default: False

Show boxplot horizontally.

label: tuple of strs, optional

Trace labels for legend.

color: tuple of strs, optional

Fill colors.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

color_median: color, default: “black”

MPL only. Color of the median line.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the boxplot core method.

add_heatmap(data, lim=(None, None), aspect=1, invert_x=False, invert_y=False, cmap='rainbow', cmap_under=None, cmap_over=None, cmap_bad=None, row=0, col=0, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw a heatmap.

Parameters:

data: 2D array-like

2D data to show heatmap.

lim: list/tuple of 2x float, optional

Lower and upper limits of the color map.

aspect: float, default: 1

Aspect ratio of the axes.

invert_x, invert_y: bool, optional

Invert the axes directions. Default: False

cmap: str, default: “rainbow”

Color map to use. https://matplotlib.org/stable/gallery/color/colormap_reference.html Note: Not all cmaps are available for both libraries, and may differ slightly.

cmap_under, cmap_over, cmap_bad: str, optional

Colors to display if under/over range or a pixel is invalid, e.g. in case of np.nan. cmap_bad is not available for interactive plotly plots.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the heatmap core method.

add_regression(x, y=None, p=0.05, linspace=101, **kwargs)

Draw a linear regression plot.

Parameters:

x: array-like or `interplot.arraytools.LinearRegression` instance

X axis data, or pre-existing LinearRegression instance.

y: array-like, optional

Y axis data. If a LinearRegression instance is provided for x, y can be omitted and will be ignored.

p: float, default: 0.05

p-value.

linspace: int, default: 101

Number of data points for linear regression model and conficence and prediction intervals.

kwargs:

Keyword arguments for interplot.arraytools.LinearRegression.plot.

add_fill(x, y1, y2=None, label=None, show_legend=False, mode='lines', color=None, opacity=0.5, line_width=0.0, line_opacity=1.0, line_color=None, row=0, col=0, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw a fill between two y lines.

Parameters:

x: array-like

y1, y2: array-like, optional

If only x and y1 is defined, it will be assumed as y1 and y2, and x will be the index, starting from 0.

label: str, optional

Trace label for legend.

color, line_color: str, optional

Fill and line color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

If line_color is undefined, the the fill color will be used.

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity, line_opacity: float, default: 0.5

Opacity (=alpha) of the fill.

Set to None to use a value provided with the color argument.

line_width: float, default: 0.

Boundary line width.

row, col: int, default: 0

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the fill core method.

add_text(x, y, text, horizontal_alignment='center', vertical_alignment='center', text_alignment=None, data_coords=None, x_data_coords=True, y_data_coords=True, color='black', opacity=None, row=0, col=0, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw text.

Parameters:

x, y: float

Coordinates of the text.

text: str

Text to add.

horizontal_alignment, vertical_alignment: str, default: “center”

Where the coordinates of the text box anchor.

Options for horizontal_alignment:

• “left”

• “center”

• “right”

Options for vertical_alignment:

• “top”

• “center”

• “bottom”

text_alignment: str, optional

Set how text is aligned inside its box.

If left undefined, horizontal_alignment will be used.

data_coords: bool, default: True

Whether the x, y coordinates are provided in data coordinates or in relation to the axes.

If set to False, x, y should be in the range (0, 1). If data_coords is set, it will override x_data_coords and y_data_coords.

x_data_coords, y_data_coords: bool, default: True

PTY only. Specify the anchor for each axis separate.

color: str, default: “black”

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

post_process(global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None)

Finish the plot.

Parameters:

Note: If not provided, the parameters given on init or

the `interplot.conf` default values will be used.

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

If providing your own function reference, conf.MPL_CUSTOM_FUNC will not be executed.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

If providing your own function reference, conf.PTY_CUSTOM_FUNC will not be executed.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

save(path, export_format=None, print_confirm=True, **kwargs)

Save the plot.

Parameters:

path: str, pathlib.Path, bool

May point to a directory or a filename. If only a directory is provided (or True for local directory), the filename will automatically be generated from the plot title.

An iterable of multiple paths may be provided. In this case the save command will be repeated for each element.

export_format: str, optional

If the format is not indicated in the file name, specify a format.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

print_confirm: bool, optional

Print a confirmation message where the file has been saved. Default: True

Returns:

pathlib.Path

Path to the exported file.

show()

Show the plot.

close()

Close the plot.

_repr_mimebundle_(*args, **kwargs)

Call forward to self.show()_repr_mimebundle_()

_repr_html_()

Call forward to self.show()._repr_html_().

JS_RENDER_WARNING = ''

Type:    str

One-line Plotting

interplot.line(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw a line or scatter plot.

Parameters:

x: array-like

y: array-like, optional

If only x is defined, it will be assumed as y. If a pandas Series is provided, the index will be taken as x. Else if a pandas DataFrame is provided, the method call is looped for each column. Else x will be an increment, starting from 0. If a 2D numpy array is provided, the method call is looped for each column.

x_error, y_error: number or shape(N,) or shape(2, N), optional

The errorbar sizes (matplotlib style):

• scalar: Symmetric +/- values for all data points.

• shape(N,): Symmetric +/-values for each data point.

• shape(2, N): Separate - and + values for each bar. First row

  contains the lower errors, the second row contains the upper errors.

• None: No errorbar.

mode: str, optional

Options: lines / lines+markers / markers

The default depends on the method called:

• add_line: lines

• add_scatter: markers

• add_linescatter: lines+markers

line_style: str, optional

Line style. Options: solid, dashed, dotted, dashdot

Aliases: -, –, dash, :, dot, -.

marker: int or str, optional

Marker style. If an integer is provided, it will be converted to the corresponding string marker using plotly numbering. If not provided, the default marker circle is used.

marker_size: int, optional

marker_line_width: int, optional

marker_line_color: str, optional

Can be hex, rgb(a) or any named color that is understood by matplotlib.

Default: same color as color.

label: str, optional

Trace label for legend.

show_legend: bool, optional

Whether to show the label in the legend.

By default, it will be shown if a label is defined.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

pty_marker_kwargs: dict, optional

PLOTLY ONLY.

Additional marker arguments.

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

Examples

Using the interplot.Plot method:

>>> fig = interplot.Plot(title="line, linescatter and scatter")
... fig.add_line([0,4,6,7], [1,2,4,8])
... fig.add_linescatter([0,4,6,7], [8,4,2,1])
... fig.add_scatter([0,4,6,7], [2,4,4,2], )
... fig.post_process()
... fig.show()

[plotly figure, “line, linescatter and scatter”]

Using interplot.line:

>>> interplot.line([0,4,6,7], [1,2,4,8])

>>> interplot.line(
...     x=[0,4,6,7],
...     y=[1,2,4,8],
...     interactive=False,
...     color="red",
...     title="matplotlib static figure",
...     xlabel="abscissa",
...     ylabel="ordinate",
... )

interplot.scatter(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw a line or scatter plot.

Parameters:

x: array-like

y: array-like, optional

If only x is defined, it will be assumed as y. If a pandas Series is provided, the index will be taken as x. Else if a pandas DataFrame is provided, the method call is looped for each column. Else x will be an increment, starting from 0. If a 2D numpy array is provided, the method call is looped for each column.

x_error, y_error: number or shape(N,) or shape(2, N), optional

The errorbar sizes (matplotlib style):

• scalar: Symmetric +/- values for all data points.

• shape(N,): Symmetric +/-values for each data point.

• shape(2, N): Separate - and + values for each bar. First row

  contains the lower errors, the second row contains the upper errors.

• None: No errorbar.

mode: str, optional

Options: lines / lines+markers / markers

The default depends on the method called:

• add_line: lines

• add_scatter: markers

• add_linescatter: lines+markers

line_style: str, optional

Line style. Options: solid, dashed, dotted, dashdot

Aliases: -, –, dash, :, dot, -.

marker: int or str, optional

Marker style. If an integer is provided, it will be converted to the corresponding string marker using plotly numbering. If not provided, the default marker circle is used.

marker_size: int, optional

marker_line_width: int, optional

marker_line_color: str, optional

Can be hex, rgb(a) or any named color that is understood by matplotlib.

Default: same color as color.

label: str, optional

Trace label for legend.

show_legend: bool, optional

Whether to show the label in the legend.

By default, it will be shown if a label is defined.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

pty_marker_kwargs: dict, optional

PLOTLY ONLY.

Additional marker arguments.

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

Examples

Using the interplot.Plot method:

>>> fig = interplot.Plot(title="line, linescatter and scatter")
... fig.add_line([0,4,6,7], [1,2,4,8])
... fig.add_linescatter([0,4,6,7], [8,4,2,1])
... fig.add_scatter([0,4,6,7], [2,4,4,2], )
... fig.post_process()
... fig.show()

[plotly figure, “line, linescatter and scatter”]

Using interplot.line:

>>> interplot.line([0,4,6,7], [1,2,4,8])

>>> interplot.line(
...     x=[0,4,6,7],
...     y=[1,2,4,8],
...     interactive=False,
...     color="red",
...     title="matplotlib static figure",
...     xlabel="abscissa",
...     ylabel="ordinate",
... )

interplot.linescatter(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw a line or scatter plot.

Parameters:

x: array-like

y: array-like, optional

If only x is defined, it will be assumed as y. If a pandas Series is provided, the index will be taken as x. Else if a pandas DataFrame is provided, the method call is looped for each column. Else x will be an increment, starting from 0. If a 2D numpy array is provided, the method call is looped for each column.

x_error, y_error: number or shape(N,) or shape(2, N), optional

The errorbar sizes (matplotlib style):

• scalar: Symmetric +/- values for all data points.

• shape(N,): Symmetric +/-values for each data point.

• shape(2, N): Separate - and + values for each bar. First row

  contains the lower errors, the second row contains the upper errors.

• None: No errorbar.

mode: str, optional

Options: lines / lines+markers / markers

The default depends on the method called:

• add_line: lines

• add_scatter: markers

• add_linescatter: lines+markers

line_style: str, optional

Line style. Options: solid, dashed, dotted, dashdot

Aliases: -, –, dash, :, dot, -.

marker: int or str, optional

Marker style. If an integer is provided, it will be converted to the corresponding string marker using plotly numbering. If not provided, the default marker circle is used.

marker_size: int, optional

marker_line_width: int, optional

marker_line_color: str, optional

Can be hex, rgb(a) or any named color that is understood by matplotlib.

Default: same color as color.

label: str, optional

Trace label for legend.

show_legend: bool, optional

Whether to show the label in the legend.

By default, it will be shown if a label is defined.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

pty_marker_kwargs: dict, optional

PLOTLY ONLY.

Additional marker arguments.

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

Examples

Using the interplot.Plot method:

>>> fig = interplot.Plot(title="line, linescatter and scatter")
... fig.add_line([0,4,6,7], [1,2,4,8])
... fig.add_linescatter([0,4,6,7], [8,4,2,1])
... fig.add_scatter([0,4,6,7], [2,4,4,2], )
... fig.post_process()
... fig.show()

[plotly figure, “line, linescatter and scatter”]

Using interplot.line:

>>> interplot.line([0,4,6,7], [1,2,4,8])

>>> interplot.line(
...     x=[0,4,6,7],
...     y=[1,2,4,8],
...     interactive=False,
...     color="red",
...     title="matplotlib static figure",
...     xlabel="abscissa",
...     ylabel="ordinate",
... )

interplot.bar(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw a bar plot.

Parameters:

x: array-like

y: array-like, optional

If only either x or y is defined, it will be assumed as the size of the bar, regardless whether it’s horizontal or vertical. If both x and y are defined, x will be taken as the position of the bar, and y as the size, regardless of the orientation. If a pandas Series is provided, the index will be taken as the position. Else if a pandas DataFrame is provided, the method call is looped for each column. If a 2D numpy array is provided, the method call is looped for each column, with the index as the position.

horizontal: bool, optional

If True, the bars are drawn horizontally. Default is False.

width: float, optional

Relative width of the bar. Must be in the range (0, 1).

label: str, optional

Trace label for legend.

show_legend: bool, optional

Whether to show the label in the legend.

By default, it will be shown if a label is defined.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

line_width: float, optional

The width of the bar outline. Default is 1.

line_color: str, optional

The color of the bar outline. This can be a named color or a tuple specifying the RGB values.

By default, the same color as the fill is used.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

interplot.hist(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw a histogram.

Parameters:

x: array-like

Histogram data.

bins: int, optional

Number of bins. If undefined, plotly/matplotlib will detect automatically. Default: None

label: str, optional

Trace label for legend.

color: str, optional

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, default: 0

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the hist core method.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

interplot.boxplot(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw a boxplot.

Parameters:

x: array or sequence of vectors

Data to build boxplot from.

horizontal: bool, default: False

Show boxplot horizontally.

label: tuple of strs, optional

Trace labels for legend.

color: tuple of strs, optional

Fill colors.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

color_median: color, default: “black”

MPL only. Color of the median line.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the boxplot core method.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

interplot.heatmap(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw a heatmap.

Parameters:

data: 2D array-like

2D data to show heatmap.

lim: list/tuple of 2x float, optional

Lower and upper limits of the color map.

aspect: float, default: 1

Aspect ratio of the axes.

invert_x, invert_y: bool, optional

Invert the axes directions. Default: False

cmap: str, default: “rainbow”

Color map to use. https://matplotlib.org/stable/gallery/color/colormap_reference.html Note: Not all cmaps are available for both libraries, and may differ slightly.

cmap_under, cmap_over, cmap_bad: str, optional

Colors to display if under/over range or a pixel is invalid, e.g. in case of np.nan. cmap_bad is not available for interactive plotly plots.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the heatmap core method.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

interplot.regression(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw a linear regression plot.

Parameters:

x: array-like or `interplot.arraytools.LinearRegression` instance

X axis data, or pre-existing LinearRegression instance.

y: array-like, optional

Y axis data. If a LinearRegression instance is provided for x, y can be omitted and will be ignored.

p: float, default: 0.05

p-value.

linspace: int, default: 101

Number of data points for linear regression model and conficence and prediction intervals.

kwargs:

Keyword arguments for interplot.arraytools.LinearRegression.plot.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

interplot.fill(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw a fill between two y lines.

Parameters:

x: array-like

y1, y2: array-like, optional

If only x and y1 is defined, it will be assumed as y1 and y2, and x will be the index, starting from 0.

label: str, optional

Trace label for legend.

color, line_color: str, optional

Fill and line color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

If line_color is undefined, the the fill color will be used.

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity, line_opacity: float, default: 0.5

Opacity (=alpha) of the fill.

Set to None to use a value provided with the color argument.

line_width: float, default: 0.

Boundary line width.

row, col: int, default: 0

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the fill core method.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

interplot.text(*args, fig=None, skip_post_process=False, interactive=None, rows=1, cols=1, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, shared_xaxes=False, shared_yaxes=False, column_widths=None, row_heights=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, color_cycle=None, save_fig=None, save_format=None, save_config=None, global_custom_func=None, mpl_custom_func=None, pty_custom_func=None, pty_update_layout=None, **kwargs)

Draw text.

Parameters:

x, y: float

Coordinates of the text.

text: str

Text to add.

horizontal_alignment, vertical_alignment: str, default: “center”

Where the coordinates of the text box anchor.

Options for horizontal_alignment:

• “left”

• “center”

• “right”

Options for vertical_alignment:

• “top”

• “center”

• “bottom”

text_alignment: str, optional

Set how text is aligned inside its box.

If left undefined, horizontal_alignment will be used.

data_coords: bool, default: True

Whether the x, y coordinates are provided in data coordinates or in relation to the axes.

If set to False, x, y should be in the range (0, 1). If data_coords is set, it will override x_data_coords and y_data_coords.

x_data_coords, y_data_coords: bool, default: True

PTY only. Specify the anchor for each axis separate.

color: str, default: “black”

Trace color.

Can be hex, rgb(a) or any named color that is understood by matplotlib.

The color cycle can be accessed with “C0”, “C1”, …

Default: color is retrieved from Plot.digest_color, which cycles through COLOR_CYCLE.

opacity: float, optional

Opacity (=alpha) of the fill.

By default, fallback to alpha value provided with color argument, or 1.

row, col: int, optional

If the plot contains a grid, provide the coordinates.

Attention: Indexing starts with 0!

kwargs_pty, kwargs_mpl, **kwargs: optional

Pass specific keyword arguments to the line core method.

interactive: bool, default: True

Display an interactive plotly line plot instead of the default matplotlib figure.

rows, cols: int, default: 1

Create a grid with n rows and m columns.

title: str, default: None

Plot title.

xlabel, ylabel: str or str tuple, default: None

Axis labels.

Either one title for the entire axis or one for each row/column.

xlim, ylim: tuple of 2 numbers or nested, default: None

Axis range limits.

In case of multiple rows/cols provide either:

• a tuple

• a tuple for each row

• a tuple for each row containing a tuple for each column.

xlog, ylog: bool or bool tuple, default: False

Logarithmic scale for the axis.

Either one boolean for the entire axis or one for each row/column.

shared_xaxes, shared_yaxes: str, default: None

Define how multiple subplots share there axes.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

column_widths, row_heights: tuple/list, default: None

Ratios of the width/height dimensions in each column/row. Will be normalised to a sum of 1.

fig_size: tuple of 2x float, optional

Width, height in pixels.

Default behavior defined by conf.MPL_FIG_SIZE and conf.PTY_FIG_SIZE. Plotly allows None for responsive size adapting to viewport.

dpi: int, default: 100

Plot resolution.

legend_loc: str, optional

MATPLOTLIB ONLY.

Default:

• In case of 1 line: None

• In case of >1 line: “best” (auto-detect)

legend_title: str, default: None

MPL: Each subplot has its own legend, so a 2d list in the shape of the subplots may be provided.

PTY: Just provide a str.

color_cycle: list, optional

Cycle through colors in the provided list.

If left None, the default color cycle conf.COLOR_CYCLE will be used.

save_fig: str or pathlib.Path, default: None

Provide a path to export the plot.

Possible formats: png, jpg, svg, html, …

The figure will only be saved on calling the instance’s .post_process().

If a directory (or True for local directory) is provided, the filename will be automatically generated based on the title.

An iterable of multiple paths / filenames may be provided. In this case the save command will be repeated for each element.

save_format: str, default: None

Provide a format for the exported plot, if not declared in save_fig.

An iterable of multiple formats may be provided. In this case the save command will be repeated for each element.

save_config: dict, default: None

Plotly only.

Pass config options to plotly.graph_objects.Figure.write_html(config=save_config).

global_custom_func: function, default: None

Pass a function reference to further style the figures.

>>> def global_custom_func(fig):
...     # do your customisations
...     fig.add_text(0, 0, "watermark", color="gray")
...
...     # also include default function
...     conf.GLOBAL_CUSTOM_FUNC(fig)
...
... fig = interplot.Plot(
...     global_custom_func=global_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # global_custom_func will be executed here
... fig.show()

mpl_custom_func: function, default: None

MATPLOTLIB ONLY.

Pass a function reference to further style the matplotlib graphs. Function must accept fig, ax and return fig, ax.

Note: ax always has row and col coordinates, even if the plot is just 1x1.

>>> def mpl_custom_func(fig, ax):
...     # do your customisations
...     fig.do_stuff()
...     ax[0, 0].do_more()
...
...     # also include default function
...     fig, ax = conf.MPL_CUSTOM_FUNC(fig, ax)
...
...     return fig, ax
...
... fig = interplot.Plot(
...     interactive=False,
...     mpl_custom_func=mpl_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # mpl_custom_func will be executed here
... fig.show()

pty_custom_func: function, default: None

PLOTLY ONLY.

Pass a function reference to further style the plotly graphs. Function must accept fig and return fig.

>>> def pty_custom_func(fig):
...     # do your customisations
...     fig.do_stuff()
...
...     # also include default function
...     fig = conf.PTY_CUSTOM_FUNC(fig)
...
...     return fig
...
... fig = interplot.Plot(
...     interactive=True,
...     pty_custom_func=pty_custom_func
... )
... fig.add_line(x, y)
... fig.post_process()  # pty_custom_func will be executed here
... fig.show()

pty_update_layout: dict, default: None

PLOTLY ONLY.

Pass keyword arguments to plotly’s plotly.graph_objects.Figure.update_layout(**pty_update_layout)

Default: None

Returns:

interplot.Plot instance

magic_plot decorators

interplot.magic_plot(core, doc_decorator=None)

Plot generator wrapper.

Your function feeds the data, the wrapper gives control over the plot to the user.

Parameters:

doc_decorator: str, optional

Append the docstring with the decorated parameters.

By default, the global variable _DOCSTRING_DECORATOR will be used.

Examples

>>> @interplot.magic_plot
... def plot_lines(samples=100, n=10, label="sigma={0}, mu={1}", fig=None):
...     """
...     Plot Gaussian noise.
...
...     The function must accept the `fig` parameter from the decorator.
...     """
...     for i in range(1, n+1):
...         fig.add_line(
...             np.random.normal(i*10,i,samples),
...             label=label.format(i, i*10),
...         )

>>> plot_lines(samples=200, title="Normally distributed Noise")

>>> plot_lines(
...     samples=200, interactive=False, title="Normally distributed Noise")

interplot.magic_plot_preset(doc_decorator=None, **kwargs_preset)

Plot generator wrapper, preconfigured.

Your function feeds the data, the wrapper gives control over the plot to the user.

Parameters:

doc_decorator: str, optional

Append the docstring with the decorated parameters.

By default, the global variable conf._DOCSTRING_DECORATOR will be used.

**kwargs_preset: dict

Define presets for any keyword arguments accepted by Plot.

Setting strict_preset=True prevents overriding the preset.

Examples

>>> @interplot.magic_plot_preset(
...     title="Data view",
...     interactive=False,
...     strict_preset=False,
... )
... def line(
...     data,
...     fig,
...     **kwargs,
... ):
...     fig.add_line(data)
...
... line([0,4,6,7], xlabel="X axis")

[matplotlib figure, “Data view”]

NotebookInteraction Parent Class

class interplot.NotebookInteraction

Bases: object

Parent class for automatic display in Jupyter Notebook.

Calls the child’s show()._repr_html_() for automatic display in Jupyter Notebooks.

Methods

__call__(*args, **kwargs)

Calls the self.show() or self.plot() method.

JS_RENDER_WARNING = ''

Type:    str

_repr_html_()

Call forward to self.show()._repr_html_().

_repr_mimebundle_(*args, **kwargs)

Call forward to self.show()_repr_mimebundle_()

ShowDataArray, ShowDataset

class interplot.ShowDataArray(data, default_sel=None, default_isel=None)

Bases: NotebookInteraction

Automatically display a xarray.DataArray in a Jupyter notebook.

If the DataArray has more than two dimensions, provide default sel or isel selectors to reduce to two dimensions.

Parameters:

data: xarray.DataArray

default_sel: dict, optional

Select a subset of a the DataArray by label. Can be a slice or the type of the dimension.

default_isel: dict, optional

Select a subset of a the DataArray by integer count. Can be a integer slice or an integer.

Methods

__call__(*args, **kwargs)	Calls the self.show() or self.plot() method.
plot(*args[, sel, isel])	Show the DataArray.

plot(*args, sel=None, isel=None, **kwargs)

Show the DataArray.

Parameters:

sel: dict, optional

Select a subset of a the DataArray by label. Can be a slice or the type of the dimension. If None, default_sel will be used.

isel: dict, optional

Select a subset of a the DataArray by integer count. Can be a integer slice or an integer. If None, default_isel will be used.

Returns:

Plot.fig

JS_RENDER_WARNING = ''

Type:    str

_repr_html_()

Call forward to self.show()._repr_html_().

_repr_mimebundle_(*args, **kwargs)

Call forward to self.show()_repr_mimebundle_()

class interplot.ShowDataset(data, default_var=None, default_sel=None, default_isel=None)

Bases: ShowDataArray

Automatically display a xarray.Dataset in a Jupyter notebook.

Provide a default variable to display from the Dataset for automatic display. If the Dataset has more than two dimensions, provide default sel or isel selectors to reduce to two dimensions.

Parameters:

data: xarray.DataArray

default_var: str, optional

Select the variable of the Dataset to display by label.

default_sel: dict, optional

Select a subset of a the Dataset by label. Can be a slice or the type of the dimension.

default_isel: dict, optional

Select a subset of a the Dataset by integer count. Can be a integer slice or an integer.

Methods

__call__(*args, **kwargs)	Calls the self.show() or self.plot() method.
plot(*args[, var, sel, isel])	Show a variable of the Dataset.

JS_RENDER_WARNING = ''

Type:    str

_repr_html_()

Call forward to self.show()._repr_html_().

_repr_mimebundle_(*args, **kwargs)

Call forward to self.show()_repr_mimebundle_()

plot(*args, var=None, sel=None, isel=None, **kwargs)

Show a variable of the Dataset.

Parameters:

var: str, optional

Select the variable of the Dataset to display by label. If None, default_var will be used.

sel: dict, optional

Select a subset of a the DataArray by label. Can be a slice or the type of the dimension. If None, default_sel will be used.

isel: dict, optional

Select a subset of a the DataArray by integer count. Can be a integer slice or an integer. If None, default_isel will be used.

Returns:

Plot.fig

Helper functions

interplot.pick_non_none(*args, fail=False)

Return the first non-None argument.

Parameters:

*args: any

Any number of arguments.

fail: bool, default: False

Throw a ValueError if all args are None.

If set to False, None will be returned.

Returns:

any

The first non-None argument.