# `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.