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 and image 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, legend_togglegroup=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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, mode, color, ...])	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_image(x, y, image[, ...])	Draw an image.
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 matplotlib 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, ...])	Save the plot.
show()	Show the plot.
update([title, xlabel, ylabel, xlim, ylim, ...])	Update plot parameters set during initialisation.

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__.

update(title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xlog=None, ylog=None, fig_size=None, dpi=None, legend_loc=None, legend_title=None, legend_togglegroup=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)

Update plot parameters set during initialisation.

Parameters:

interactive: bool, default: True

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

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.

Options:

• “all” or True

• “rows”

• “columns” or “cols”

• None or False

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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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(fig_size=(600, 400))
... fig.add_line((1,2,4,3))
... fig.save("export_landscape.png")
... fig.save("export_fullsize.html")
... fig.update(fig_size=(400, 600))
... fig.save("export_portrait.png")

>>> @interplot.magic_plot
... def plot_points(data, fig=None):
...     fig.add_line(data)
...     fig.update(title="SUM: {}".format(sum(data)))
... plot_points([1,2,4,3])

get_cycle_color(increment=1, i=None)

Retrieves the next color in the color cycle.

Parameters:

increment: int, default: 1

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

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.

By default, alpha is derived from color, otherwise set to 1.

increment: int, default: 1

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.

recursive: bool, default: False

Signals that the method was called from within digest_marker recursively.

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.

By default, the same color as color will be used.

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”, …

By default, the 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.

By default, the same color as color will be used.

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”, …

By default, the 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.

By default, the same color as color will be used.

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”, …

By default, the 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”, …

By default, the 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.

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”, …

By default, the 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”, …

By default, the 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, default: False

Invert the axes directions.

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, 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 or interplot.LabelGroup, 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.

By default, the 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”, …

By default, the 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.

add_image(x, y, image, horizontal_alignment='center', vertical_alignment='center', data_coords=True, x_size=1, y_size=1, sizing='contain', opacity=None, row=0, col=0, kwargs_pty=None, kwargs_mpl=None, **kwargs)

Draw an image.

Parameters:

x, y: float

Coordinates of the text.

image: Image object or str

The image as a PIL Image object.

For plotly, URLs are also accepted.

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”

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].

sizing: str, default: “contain”

How the image should be sized.

Options:

• “contain”: fit the image inside the box. The entire image

will be visible, and the aspect ratio will be preserved. - “stretch”: stretch the image to fit the box. The image may be distorted. - “fill”: fill the box with the image. The image may be cropped, but will keep its aspect ratio. Only available for plotly.

opacity: float, optional

Opacity (=alpha) of the fill.

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, html_no_fig_size=True, 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.

If none is provided, the format will be derived from the filename.

html_no_fig_size: bool, default: True

Allow the HTML plot to use the entire window and auto-scale upon window resizing.

print_confirm: bool, default: True

Print a confirmation message where the file has been saved.

Returns:

pathlib.Path

Path to the exported file.

show()

Show the plot.

close()

Close the matplotlib 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, 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, legend_togglegroup=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.

By default, the same color as color will be used.

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”, …

By default, the 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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, 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, legend_togglegroup=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.

By default, the same color as color will be used.

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”, …

By default, the 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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, 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, legend_togglegroup=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.

By default, the same color as color will be used.

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”, …

By default, the 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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, 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, legend_togglegroup=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”, …

By default, the 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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, 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, legend_togglegroup=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.

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”, …

By default, the 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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, 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, legend_togglegroup=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”, …

By default, the 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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, 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, legend_togglegroup=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, default: False

Invert the axes directions.

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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, 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, legend_togglegroup=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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, 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, legend_togglegroup=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 or interplot.LabelGroup, 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.

By default, the 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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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, 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, legend_togglegroup=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”, …

By default, the 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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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.image(*args, fig=None, skip_post_process=False, 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, legend_togglegroup=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 an image.

Parameters:

x, y: float

Coordinates of the text.

image: Image object or str

The image as a PIL Image object.

For plotly, URLs are also accepted.

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”

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].

sizing: str, default: “contain”

How the image should be sized.

Options:

• “contain”: fit the image inside the box. The entire image

will be visible, and the aspect ratio will be preserved. - “stretch”: stretch the image to fit the box. The image may be distorted. - “fill”: fill the box with the image. The image may be cropped, but will keep its aspect ratio. Only available for plotly.

opacity: float, optional

Opacity (=alpha) of the fill.

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.

legend_togglegroup: bool, default: False

PLOTLY ONLY.

Whether legend items with the same group will be toggled together when clicking on a legend item.

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.

strict_preset: bool, default: False

Prevents overriding the preset upon calling the decorated function.

**kwargs_preset: dict

Define presets for any keyword arguments accepted by Plot.

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”]

LabelGroup class

class interplot.LabelGroup(group_title=None, group_id=None, default_show=True, default_label=None, default_legend_only=False)

Bases: object

Grouping Labels in interactive plots.

Grouping is not supported in matplotlib legends. In matplotlib, only the label and show parameters are used.

Toggling behavior can be set via ip.Plot(…, legend_togglegroup=<bool>) or globally with conf.PTY_LEGEND_TOGGLEGROUP.

Parameters:

group_title: str, optional

Group title for the legend group. Will be shown above the group if specified.

group_id: str, optional

Must be unique for each group. If none is provided, a UUID will be generated.

default_show: bool or “first”, default: True

Whether to show the label in the legend.

If set to “first”, the element dispatcher will check, whether the figure instance already has an trace of this group_id. If not, the label will be shown in the legend, otherwise it won’t.

default_label: str, optional

Default label for elements in this group.

default_legend_only: bool, default: False

Whether to show the trace only in the legend by default.

Methods

__call__(*args, **kwargs)	Return an element with the default parameters.
element([label, show, legend_only])	Define a label for an element in this group.

element(label=None, show=None, legend_only=None)

Define a label for an element in this group.

Parameters:

label: str, optional

Label for the element.

If not specified, the default label will be used.

show: bool, optional

Whether to show the label in the legend.

If not specified, the default show value will be used.

legend_only: bool, optional

Whether to show the trace only in the legend.

If not specified, the default legend_only value will be used.

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.init_notebook_mode(connected=False)

Initialize plotly.js in the browser if not already done, and deactivate matplotlib auto-display.

Parameters:

connected: bool, default: True

If True, the plotly.js library will be loaded from an online CDN. If False, the plotly.js library will be loaded locally.

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.

interplot.close()

Close all open matplotlib figures.