PlotPanel: A wx.Panel for Basic Line Plots

The PlotPanel class supports standard line plots, including scatter plots. It has both an easy-to-use programming interface, and a rich graphical user interface for manipulating the plot after it has been drawn. The PlotPanel class is derived from a wx.Panel and so that it can be included anywhere in a wx Window object that a normal wx.Panel can be put. In addition to drawing a plot, a PlotPanel provides the following capabilities to the end-user:

  1. display x, y coordinates as the mouse move.

  2. display x, y coordinates of last left-click.

  3. zoom in on a particular region of the plot with left-drag in a lineplot, or draw a ‘lasso’ around selected points in a scatterplot.

  4. customize titles, labels, legend, colors, linestyles, markers, and whether a grid and a legend is shown. A separate configuration window is displayed to give users control of these settings.

  5. save high-quality plot images (as PNGs), or copy to system clipboard, or print.

In addition, there is a PlotFrame widget which creates a stand-alone wx.Frame that contains a PlotPanel, a wx.StatusBar, and a wx.MenuBar. Both PlotPanel and PlotFrame classes have the basic plotting methods of plot() to make a new plot with a single trace, and oplot() to overplot another trace on top of an existing plot. These each take 2 equal-length numpy arrays (abscissa, ordinate) for each trace, and a host of optional arguments. The PlotPanel and PlotFrame have many additional methods to interact with the plots.

class PlotPanel(parent, size=(700, 450), dpi=150, fontsize=9, **kws)

Create a Plot Panel, a wx.Panel with a matplotlib Figure. This takes many optional arguments:

Parameters:
  • parent – wx parent object.

  • size (wx.Size or tuple of 2 integers.) – figure size in wxPython pixel coordinates ((700, 450)).

  • dpi (integer) – dots per inch for figure (150).

  • axisbg (valid colour name) – background colour for Axis (‘#FEFEFE’).

  • fontsize (integer) – font size for wxFont for labels and ticks (9).

  • output_title – string to use for output plots (‘plot’).

  • messenger (callable or None) – function to use for writing output messages (None).

  • trace_color_callback (callable or None) – function to call when a color changes (None).

  • show_config_popup (True/False) – whether to enable a popup-menu on right-click.

The size, and dpi arguments are sent to matplotlib’s Figure. The messenger should should be a function that accepts text messages from the panel for informational display. The default value is to use sys.stdout.write().

The show_config_popup arguments controls whether to bind right-click to showing a poup menu with options to zoom in or out, configure the plot, or save the image to a file.

Keyword parameters in **kws other than those listed above are sent to the wx.Panel.

PlotPanel methods

plot(x, y, **kws)

Draw a plot of the numpy arrays x and y, erasing any existing plot. The displayed curve for these data is called a trace. The plot() method has many optional parameters, all using keyword/value argument. Since most of these are shared with the oplot() method, the full set of parameters is given in Table of Plot Arguments

oplot(x, y, **kws)

Draw a plot of the numpy arrays x and y, overplotting any existing plot, so that both traces are visible.

The oplot() method has many optional parameters, as listed in Table of Plot Arguments

Table of Plot Arguments These arguments apply for the plot(), oplot(), and scatterplot() methods. Except where noted, the arguments are available for plot() and oplot(). In addition, the scatterplot() method uses many of the same arguments for the same meaning, as indicated by the right-most column.

argument

type

default

meaning

note

scatterplot?

title

string

None

Plot title

1

yes

ylabel

string

None

abscissa label

1

yes

y2label

string

None

right-hand abscissa label

1

yes

label

string

None

trace label (defaults to ‘trace N’)

1

yes

theme

str

‘’

theme for colors and text size

2

no

color

string

blue

color to use for trace

3

yes

bgcolor

string

#FEFEFE

color for background of Axis (plot area)

3

yes

framecolor

string

white

color for frame outside Axis

3

yes

gridcolor

string

#E5E5E5

color for grid lines

3

yes

linewidth

int

2

linewidth for trace

no

alpha

float

1.0

opacity (from 0 to 1) for trace

4

no

fill

bool

False

fill to 0 or between [y-dy,y+dy]

5

no

zorder

int

10

depth order of trace (what trace is on top)

6

no

style

string

solid

line-style for trace (solid, dashed, …)

7

no

drawstyle

string

line

style connecting points of trace

8

no

side

left/right

left

side for y-axis and label

yes

marker

string

None

symbol to show for each point (+, o, ….)

9

no

markersize

int

8

size of marker shown for each point

no

legendfontsize

int

7

text size for legend

yes

labelfontsize

int

9

text size for Axis labels

yes

dy

array

None

uncertainties for y values; error bars

no

xmin

float

None

minimum displayed x value

10

yes

xmax

float

None

maximum displayed x value

10

yes

ymin

float

None

minimum displayed y value

10

yes

ymax

float

None

maximum displayed y value

10

yes

viewpad

float

2.5

percent past data range to pad data limits

10

yes

ylog_scale

bool

False

draw y axis with log(base 10) scale

no

autoscale

bool

True

whether to automatically set plot limits

no

fullbox

bool

True

whether to show top and right Axes lines

11

no

axes_style

string

‘box’

whether to show top, left, right Axes lines

11

no

grid

None/bool

None

to show grid lines

yes

show_legend

None/bool

None

whether to display legend (None: leave as is)

no

legend_loc

string

‘ur’

location of legend

12

no

legend_on

bool

True

whether legend is on Axis

12

no

delay_draw

bool

False

whether to delay draw until later.

13

no

refresh

bool

True

whether to refresh display

no

use_dates

bool

False

to show dates in xlabel (plot() only)

14

no

dates_style

str

‘’

aid conversion of floats to time data

14

no

arguments that apply only for scatterplot()

size

int

10

size of marker

yes

edgecolor

string

black

edge color of marker

3

yes

selectcolor

string

red

color for selected points

3

yes

callback

function

None

user-supplied callback to run on selection

yes

As a general note, the configuration for the plot (title, labels, grid displays) and for each trace (color, linewidth, …) are preserved for a PlotPanel. A few specific notes:

  1. The title, label, and grid arguments to plot() default to None, which means to use the previously used value.

  2. The theme will set the color palette and make stylistic choices. Choices include ‘light’ (the default), ‘white-background’, ‘dark’, ‘matplotlib’, ‘seaborn’, ‘ggplot’, ‘bmh’, ‘fivethirtyeight’, ‘grayscale’, ‘dark_background’, ‘tableau-colorblind10’, ‘seaborn-bright’, ‘seaborn-colorblind’, ‘seaborn-dark’, ‘seaborn-darkgrid’, ‘seaborn-dark-palette’, ‘seaborn-deep’, ‘seaborn-notebook’, ‘seaborn-muted’, ‘seaborn-pastel’, ‘seaborn-paper’, ‘seaborn-poster’, ‘seaborn-talk’, ‘seaborn-ticks’, ‘seaborn-white’, ‘seaborn-whitegrid’, and

  3. All color arguments can be a common color name (“blue”, “red”, “black”, etc), a standard X11 color names (“cadetblue3”, “darkgreen”, etc), or an RGB hex color string of the form “#RRGGBB”.

  4. The alpha opacity value ranges from 0 (transpaent) to 1 (opaque) for the color used for the line trace and the fill. While supplying a color string of the form “#RRGGBBAA” can also set alpha, setting it directly here is more robust and should be preferred.

  5. The fill value controls whether to fill under the curve to 0. When dy is supplied for errorbars, using fill=True will not show error bars as vertical lines, but fill in the curve between y-dy and y+dy.

  6. zorder is the depth (that is, height above the plane of the screen) to draw the object at, controlling which element will be on top of others. By default, each oplot() plots at a zorder of 10*(n+1), where n is the counter for the trace. That is, each subsequent trace is drawn over the previous, by defualt.

  7. style is one of (‘solid’, ‘dashed’, ‘short dashed’, ‘long dashed’, ‘dotted’, or ‘dash-dot’)

  8. drawstyles is one of (None, ‘steps-pre’, ‘steps-mid’, or ‘steps-post’). None connects points with a straight line between points. The others give horizontal lines with a vertical step at the starting point (‘step-pre’), mid-point (‘step-mid’) the ending point (‘steps-post’). Note that if displaying discrete values as a function of time, left-to-right, and want to show a transition to a new value as a sudden step, you want ‘steps-post’.

  9. marker is one of (‘+’, ‘o’, ‘x’, ‘^’, ‘v’, ‘>’, ‘<’, ‘|’, ‘_’, ‘square’, ‘diamond’, ‘thin diamond’, ‘hexagon’, ‘pentagon’, ‘tripod 1’, or ‘tripod 2’).

  10. By default, xmin, xmax, ymin, and ymax are set from the data. viewpad gives a percentage of the data range for the view to be extended. That is, with xmin=0, xmin=100, viewpad=5, the range for x will be [-5, 105].

  11. fullbox can be used to turn on or off the top and right Axes lines (or spines), giving a more open figure. The ‘axes_style’ option gives a little more control – you can set this to either ‘box’ for a complete box, ‘open’ for left and right Axes lines only (same as fullbox=False), or ‘bottom’ which will suppress the top, right, and left Axes.

  12. legend_loc sets the position of the legend on the plot, and is one of ‘ur’, ‘ul’, ‘cr’, ‘cl’, ‘lr’ ‘ll’, ‘uc’, ‘lc’, or ‘cc’ for ‘upper right’ , ‘upper left’, ‘center right’, ‘center left’, ‘lower right’, ‘lower left’, ‘upper center’, ‘lower center’, or ‘center’.

  13. The delay_draw option will delay the actual drawing the plot to the screen. This can be give a noticeable speed up when plotting multiple line traces at once. See also plot_many() for a convenience function to plot many traces at once.

  14. For more on using data with dates or times, see Using date-time data with plot().

All of these values, and a few more settings controlling whether and how to display a plot legend can be configured interactively (see Plot Configuration).

update_line(trace, x, y, side='left', update_limits=True, draw=False)

update an existing trace.

Parameters:
  • trace – integer index for the trace (0 is the first trace)

  • x – array of x values

  • y – array of y values

  • side – which y axis to use (‘left’ or ‘right’).

  • update_limits – whether to force an update of the limits.

  • draw – whether to force a redrawing of the canvas.

This function is particularly useful for data that is changing and you wish to update traces from a previous plot() or oplot() with the new (x, y) data without completely redrawing the entire plot. Using this method is substantially faster than replotting, and should be used for dynamic plots such as a StripChart.

plot_many(xylist, side='left', title=None, xlabel=None, ylabel=None, **kws)

Plot many x, y datasets at a single time. xylist should be a list or tuple of two-element list or tuple of (x, y) data arrays. Many of the properties listed in Table of Plot Arguments can be specified.

If plotting many datasets, this method can give a significant speed-up over calling plot() followed by many calls of oplot(), as that will render the full image after each call, while the plot_many() will delay plotting until all the datasets are ready to be plotted.

scatterplot(x, y, **kws)

draws a 2d scatterplot. This is a collection of points that are not meant to imply a specific order that can be connected by a continuous line. A full list of arguments are listed in Table of Plot Arguments.

clear()

Clear the plot.

add_text(text, x, y, side='left', rotation=None, ha='left', va='center', family=None, **kws)

add text to the plot.

Parameters:
  • text – text to write

  • x – x coordinate for text

  • y – y coordinate for text

  • side – which axis to use (‘left’ or ‘right’) for coordinates.

  • rotation – text rotation: angle in degrees or ‘vertical’ or ‘horizontal’

  • ha – horizontal alignment (‘left’, ‘center’, ‘right’)

  • va – vertical alignment (‘top’, ‘center’, ‘bottom’, ‘baseline’)

  • family – name of font family (‘serif’, ‘sans-serif’, etc)

add_arrow(x1, y1, x2, y2, side='left', shape='full', color='black', wdith=0.01, head_width=0.03, overhang=0)

draw arrow from (x1, y1) to (x2, y2).

Parameters:
  • x1 – starting x coordinate

  • y1 – starting y coordinate

  • x2 – endnig x coordinate

  • y2 – ending y coordinate

  • side – which axis to use (‘left’ or ‘right’) for coordinates.

  • shape – arrow head shape (‘full’, ‘left’, ‘right’)

  • color – arrow fill color (‘black’)

  • width – width of arrow line (in points. default=0.01)

  • head_width – width of arrow head (in points. default=0.1)

  • overhang – amount the arrow is swept back (in points. default=0)

set_xylims(limits[, axes=None[, side=None]])

Set the x and y limits for a plot based on a 2x2 list.

Parameters:
  • limits (a 4-element list: [xmin, xmax, ymin, ymax]) – x and y limits

  • axes – instance of matplotlib axes to use (i.e, for right or left side y axes)

  • side – set to ‘right’ to get right-hand axes.

get_xylims()

return current x, y limits.

unzoom()

unzoom the plot. The x, y limits for interactive zooms are stored, and this function unzooms one level.

unzoom_all()

unzoom the plot to the full data range.

set_title(title)

set the plot title.

set_xlabel(label)

set the label for the ordinate axis.

set_ylabel(label)

set the label for the left-hand abscissa axis.

set_y2label(label)

set the label for the right-hand abscissa axis.

set_bgcol(color)

set the background color for the PlotPanel.

write_message(message)

write a message to the messenger. For a PlotPanel embedded in a PlotFrame, this will go the the Status Bar.

save_figure()

shows a File Dialog to save a PNG image of the current plot.

configure()

show plot configuration window for customizing plot.

reset_config()

reset the configuration to default settings.

Using date-time data with plot()

If the x values to be plotted holds date or time data, these can be handled in a few different formats. In order for the X-axis labels to be properly displayed as a string showing the date, the values must be eventually converted to a matplotlib.dates object, which uses a floating point number to represent the number of days since year 0, BCE. The wxmplot user is not expected to do this conversion.

The best way to specify datetime information is to use datetime objects from the datetime library. These will be automatically recognized and properly converted.

If the x data is a list or array of integers or floats and use_dates=True is used, the values will be interpreted as Unix timestamps (seconds since 1970), unless dates_styles=’dates’, in which case they will be interpreted as matplotlib.dates.

Finally, it is possible to pass in a list or array of strings as x, and set use_dates=True. In this case, the matplotlib.dates.datestr2num function will be used convert the string. Of course, whether this actually works well will depend on the ability of this function to parse and interpret the date strings used.

PlotFrame: a wx.Frame showing a PlotPanel

A PlotFrame is a wx.Frame – a separate window – that contains a PlotPanel and is decorated with a status bar and menubar. A PlotFrame inherits many of the methods of a PlotPanel, and simply passes the arguments along to the corresponding methods of the PlotPanel. The statusbar will display live coordintes as the mouse moves on the plot. The built-in menus include methods for saving, printing and copying an image of the plot to the system Clipboard, as well as ways to configure many of the plot attributes.

class PlotFrame(parent[, size=(700, 450)[, title=None[, **kws]]])

create a plot frame. This frame will have a panel member holding the underlying PlotPanel, and have menus and statusbar for plot interaction.

plot(x, y, **kws)

Passed to panel.plot

oplot(x, y, **kws)

Passed to panel.oplot

scatterplot(x, y, **kws)

Passed to panel.scatterplot

clear()

Passed to panel.clear

update_trace(x, y, **kws)

Passed to panel.update_trace

reset_config(x, y, **kws)

Passed to panel.reset_config

PlotApp: a wx.App showing a PlotFrame

A PlotApp is a wx.App – an application – that consists of a PlotFrame. This show a frame that is decorated with a status bar and menubar with menu items for saving, printing and configuring plots.

class PlotApp

create a plot application. This has methods plot(), oplot(), and write_message(), which are sent to the underlying PlotPanel. This allows very simple scripts which give plot interactivity and customization.