Plotlywrapper: Pythonic Plotly¶

Plotlywrapper is a thin API over Plotly. The goal is make simple plots easy to make.

Installation¶

To install, simply use pip:

pip install plotlywrapper

API¶

The API is documented in the following pages.

Charts¶

These are the basic chart types Plotlywrapper supports.

Scatter¶

line¶

plotlywrapper.line(x=None, y=None, label=None, color=None, width=None, dash=None, opacity=None, mode='lines+markers', yaxis=1, fill=None, text='', markersize=6)[source]¶

Draws connected dots.

Parameters:	x (array-like, optional) – y (array-like, optional) – label (array-like, optional) –
Returns:
Return type:	Chart

Examples

line(range(1, 6))

scatter¶

plotlywrapper.scatter(x=None, y=None, label=None, color=None, width=None, dash=None, opacity=None, markersize=6, yaxis=1, fill=None, text='', mode='markers')[source]¶

Draws dots.

Parameters:	x (array-like, optional) – y (array-like, optional) – label (array-like, optional) –
Returns:
Return type:	Chart

Examples

scatter(range(1, 6))

Bar¶

bar¶

plotlywrapper.bar(x=None, y=None, label=None, mode='group', yaxis=1, opacity=None)[source]¶

Create a bar chart.

Parameters:	x (array-like, optional) – y (TODO, optional) – label (TODO, optional) – mode ('group' or 'stack', default 'group') – opacity (TODO, optional) –
Returns:	A Chart with bar graph data.
Return type:	Chart

Examples

bar(range(1, 6))

Histogram¶

hist¶

plotlywrapper.hist(x, mode='overlay', label=None, opacity=None, horz=False, histnorm=None)[source]¶

Histogram.

Parameters:	x (array-like) – mode (str, optional) – label (TODO, optional) – opacity (float, optional) – horz (bool, optional) – histnorm (None, "percent", "probability", "density", "probability density", optional) – Specifies the type of normalization used for this histogram trace. If `None`, the span of each bar corresponds to the number of occurrences (i.e. the number of data points lying inside the bins). If “percent”, the span of each bar corresponds to the percentage of occurrences with respect to the total number of sample points (here, the sum of all bin area equals 100%). If “density”, the span of each bar corresponds to the number of occurrences in a bin divided by the size of the bin interval (here, the sum of all bin area equals the total number of sample points). If “probability density”, the span of each bar corresponds to the probability that an event will fall into the corresponding bin (here, the sum of all bin area equals 1).
Returns:
Return type:	Chart

Examples

hist(np.sin(np.linspace(0, 2*np.pi, 500)))

hist2d¶

plotlywrapper.hist2d(x, y, label=None, opacity=None)[source]¶

2D Histogram.

Parameters:	x (array-like, optional) – y (array-like, optional) – label (TODO, optional) – opacity (float, optional) –
Returns:
Return type:	Chart

Examples

hist2d(np.sin(np.linspace(0, 2*np.pi, 100)),
       np.cos(np.linspace(0, 2*np.pi, 100)))

Filled Area¶

fill_zero¶

plotlywrapper.fill_zero(x=None, y=None, label=None, color=None, width=None, dash=None, opacity=None, mode='lines+markers', **kargs)[source]¶

Fill to zero.

Parameters:	x (array-like, optional) – y (TODO, optional) – label (TODO, optional) –
Returns:
Return type:	Chart

Examples

bar(range(1, 6))

fill_between¶

plotlywrapper.fill_between(x=None, ylow=None, yhigh=None, label=None, color=None, width=None, dash=None, opacity=None, mode='lines+markers', **kargs)[source]¶

Fill between ylow and yhigh.

Parameters:	x (array-like, optional) – ylow (TODO, optional) – yhigh (TODO, optional) –
Returns:
Return type:	Chart

Examples

fill_between(range(5), range(1, 6), range(2, 12, 2))

Heatmap¶

heatmap¶

plotlywrapper.heatmap(z, x=None, y=None, colorscale='Viridis')[source]¶

Create a heatmap.

Parameters:	z (TODO) – x (TODO, optional) – y (TODO, optional) – colorscale (TODO, optional) –
Returns:
Return type:	Chart

Note: If z is 1D, then you must specify x and y as well. For example, taking a Pandas series with a time index, setting x = series.index.date and y = series.index.time, then z needs to be 1D (e.g. z = series.values). This would plot an empty chart if using a Pandas DataFrame, as df.values will result in an array of [[z1],[z2],[z3]…], which is not 1D.

Examples

heatmap(np.arange(25).reshape(5, -1))

x = np.arange(5)
heatmap(z=np.arange(25), x=np.tile(x, 5), y=x.repeat(5))

3D¶

plotlywrapper.line3d(x, y, z, label=None, color=None, width=None, dash=None, opacity=None, mode='lines+markers')[source]¶: Create a 3d line chart.

plotlywrapper.scatter3d(x, y, z, label=None, color=None, width=None, dash=None, opacity=None, mode='markers')[source]¶

Create a 3D scatter Plot.

Parameters:	x (array-like) – data on x-dimension y (array-like) – data on y-dimension z (array-like) – data on z-dimension label (TODO, optional) – mode ('group' or 'stack', default 'group') – opacity (TODO, optional) –
Returns:
Return type:	Chart

plotlywrapper.surface(x, y, z)[source]¶

Surface plot.

Parameters:	x (array-like, optional) – y (array-like, optional) – z (array-like, optional) –
Returns:
Return type:	Chart

Shapes¶

plotlywrapper.vertical(x, ymin=0, ymax=1, color=None, width=None, dash=None, opacity=None)[source]¶

Draws a vertical line from ymin to ymax.

Parameters:	xmin (int, optional) – xmax (int, optional) – color (str, optional) – width (number, optional) –
Returns:
Return type:	Chart

plotlywrapper.horizontal(y, xmin=0, xmax=1, color=None, width=None, dash=None, opacity=None)[source]¶

Draws a horizontal line from xmin to xmax.

Parameters:	xmin (int, optional) – xmax (int, optional) – color (str, optional) – width (number, optional) –
Returns:
Return type:	Chart

Rug¶

plotlywrapper.rug(x, label=None, opacity=None)[source]¶

Rug chart.

Parameters:	x (array-like, optional) – label (TODO, optional) – opacity (TODO, optional) –
Returns:
Return type:	Chart

Style¶

All the charting functions return a Chart instance. From this you can change various attributes of the chart, such as ticks, labels, and axes. Only a subset of Plotly’s capabilities are implemented here so if you can’t find something, take a look at the Plotly API. If you think it would be useful for others, it may be good to expose it here. Consider contributing a pull request or letting me know that it would be useful!

class plotlywrapper.Chart(data=None, layout=None, repr_plot=True)[source]¶

Plotly chart base class.

Usually this object will get created by from a function.

dict¶: Convert Chart to a dict.

group()[source]¶

Set bar graph display mode to “grouped”.

Returns:
Return type:	Chart

height¶: Height of the chart in pixels.

legend(visible=True)[source]¶

Make legend visible.

Parameters:	visible (bool, optional) –
Returns:
Return type:	Chart

save(filename: Union[str, NoneType] = None, show_link: bool = True, auto_open: bool = False, output: str = 'file', plotlyjs: bool = True) → str[source]¶: Save the chart to an html file.

show(filename: Union[str, NoneType] = None, show_link: bool = True, auto_open: bool = True, detect_notebook: bool = True) → None[source]¶

Display the chart.

Parameters:	filename (str, optional) – Save plot to this filename, otherwise it’s saved to a temporary file. show_link (bool, optional) – Show link to plotly. auto_open (bool, optional) – Automatically open the plot (in the browser). detect_notebook (bool, optional) – Try to detect if we’re running in a notebook.

stack()[source]¶

Set bar graph display mode to “stacked”.

Returns:
Return type:	Chart

title¶: Title of the chart.

width¶: Width of the chart in pixels.

xdtick(dtick)[source]¶: Set the tick distance.

xlabel¶: Xaxis Label.

xlabelsize(size)[source]¶

Set the size of the label.

Parameters:	size (int) –
Returns:
Return type:	Chart

xlim(low, high)[source]¶

Set xaxis limits.

Parameters:	low (number) – high (number) –
Returns:
Return type:	Chart

xnticks(nticks)[source]¶: Set the number of ticks.

xtickangle(angle)[source]¶

Set the angle of the x-axis tick labels.

Parameters:	value (int) – Angle in degrees
Returns:
Return type:	Chart

xticksize(size)[source]¶

Set the tick font size.

Parameters:	size (int) –
Returns:
Return type:	Chart

yaxis_left(index=1)[source]¶

Put the yaxis on the left hand side.

Parameters:	index (int, optional) –
Returns:
Return type:	Chart

yaxis_right(index=1)[source]¶

Put the yaxis on the right hand side.

Parameters:	index (int, optional) –
Returns:
Return type:	Chart

ydtick(dtick, index=1)[source]¶: Set the tick distance.

ylabel¶: Left Yaxis Label.

ylabelsize(size, index=1)[source]¶

Set the size of the label.

Parameters:	size (int) –
Returns:
Return type:	Chart

ylim(low, high, index=1)[source]¶

Set yaxis limits.

Parameters:	low (number) – high (number) – index (int, optional) –
Returns:
Return type:	Chart

ynticks(nticks, index=1)[source]¶: Set the number of ticks.

ytickangle(angle, index=1)[source]¶

Set the angle of the y-axis tick labels.

Parameters:	value (int) – Angle in degrees index (int, optional) – Y-axis index
Returns:
Return type:	Chart

yticksize(size, index=1)[source]¶

Set the tick font size.

Parameters:	size (int) –
Returns:
Return type:	Chart

yticktext(labels, index=1)[source]¶

Set the tick labels.

Parameters:	labels (array-like) –
Returns:
Return type:	Chart

ytickvals(values, index=1)[source]¶

Set the tick values.

Parameters:	values (array-like) –
Returns:
Return type:	Chart

zlabel¶: Zaxis Label.

Pandas¶

class plotlywrapper.PandasPlotting(data)[source]¶

Pandas plotly charting methods.

Examples

Here’s an example of how to do that.

>>> df = pd.DataFrame([[1, 2], [1, 4]])
>>> chart = df.plotly.line()
>>> chart.show()

bar(label=None, mode='group', opacity=None, **kargs)[source]¶

Create a bar chart.

Parameters:	label (list of strings, optional) – list of labels to override column names mode (str, optional) – ‘group’ or ‘stack’
Returns:
Return type:	Chart

line(label=None, color=None, width=None, dash=None, opacity=None, mode='lines+markers', fill=None, **kargs)[source]¶: Create a line chart.

scatter(label=None, color=None, width=None, dash=None, opacity=None, mode='markers', **kargs)[source]¶

Create a bar chart.

Parameters:	label (list of strings, optional) – list of labels to override column names
Returns:
Return type:	Chart

sparklines(label=None, mode='lines', percent=90, epsilon=0.001)[source]¶

TODO: Docstring for sparklines.

Parameters:	label (array-like, optional) – mode (str, optional) – percent (number, optional) –
Returns:
Return type:	Chart

stack(mode='lines', label=None, **kargs)[source]¶

Create a stacked area plot.

Parameters:	mode (string, optional) – label (list of strings, optional) – list of labels to override column names
Returns:
Return type:	Chart

Examples¶

Here are some more examples to highlight additional functionality.

Bubble¶

scatter(range(1, 6), markersize=numpy.arange(1, 6) * 10)

Twin Axes¶

chart = bar(range(20, 15, -1))
chart += line(range(5), yaxis=2)
chart.yaxis_right(2)

Parallel Coordinates¶

df = pd.DataFrame([[1,3,2], [2,1,3]], columns=['alpha', 'beta', 'gamma'])
chart = df.T.plotly.line()
chart.legend(False)

Unsupported Features¶

Plotlywrapper implements a small subset of Plotly’s API. If a feature isn’t implemented, you can still use Plotlywrapper and modify the data structure yourself.

Data Structure¶

First let’s learn the data structure. Plotly has two main data sources for their plots: a list of traces and layout options. The list of traces is a list of simple plot types and their data such as scatter plots, histograms, and surface plots. The Chart class stores this in its data field. The layout is a dictionary of options that globally affect the plot. The Chart class stores this in its layout field.

Examples¶

Y Axis Format¶

Change the Y Axis type to log:

chart = line(np.exp(np.arange(10)))
chart.layout['yaxis1']['type'] = 'log'