API

Expect for the templates, essentially all of the functionality is implemented in the Plot class.

Most get_* methods have been excluded below for the sake of brevity.

Index

Index

Plot

See documentation for the Plot class.

class plotbridge.plot.Plot(name=None, template='gnuplot_2d', output_dir=None, overwrite=False)

Container for a set of traces (“a plot”) and a template based system for generating a script that plots them.

Takes in global (i.e. per-plot) options together with a set of traces (data + per-trace options).

The inputs to plotbridge are (a) the data points and basic plot options from Python and (b) a template from a text file. Optionally, you can include a preprocess script (e.g. in Python) that massages the data before passing it to your plotting program.

__init__(name=None, template='gnuplot_2d', output_dir=None, overwrite=False)

Create a plot object.

Parameters:

• name – default will be ‘plot<n>’
• template – the template (e.g. ‘gnuplot_2d’) for generating the output, see the default_templates subdir for available built-in alternatives or provide a path to your own custom template.
• output_dir – where output subdir <name> should be created, default is current working dir.
• overwrite – If False, append a number to output_dir if it already exists.

add_trace(x, y=None, yerr=None, slowcoordinate=None, points=True, lines=False, skip=1, crop=0, title=None, pointtype=None, pointsize=None, linetype=None, linewidth=None, color=None, right=False, top=False, other=None, update=False, sort=None, x_plot_units=None, y_plot_units=None)

Add a 1D trace to the plot (or rather a 2D parametric curve).

Parameters:

• x,y – the x and y coordinates as two separate vectors of length N or as a Nx2 or 2xN matrix
• yerr – error bars for the ycoordinate
• slowcoordinate – second coordinate as a single scalar for the whole trace, used only in some templates (e.g. 2D color maps)
• points – draw points
• lines – connect points with lines
• skip – plot only every skip’th point
• crop – leave out crop points at each end
• title – label for this trace in a legend
• point/linetype – integer indicating the point/line style (see gnuplot pointtypes)
• point/linesize – size
• color – point/line color
• right – use the second y-axis (left = first y-axis)
• top – use the second x-axis (bottom = first x-axis)
• other – template-specific per-trace options (as a dictionary)
• update – regenerate the plot script?
• sort – if ‘x’ or ‘y’, sort the added points according to x or y first.
• x_plot_units – depracated, use set_x_units()
• y_plot_units – depracated, use set_y_units()

Returns:

a unique identifier for the trace

clear(update=False)

Remove all traces.

Parameters:update – update plot script?

get_export_formats()

Get the export formats supported by the template.

get_name(path_friendly=False)

Get the plot name.

Parameters:path_friendly – replace potentially problematic characters by “_”

get_ntraces(left=True, right=True)

Number of traces. Count trace on left and/or right y-axis.

get_output_dir()

Get output dir name.

get_template()

returns the full path to the .template file used for this plot as a triple (directory, filname, extension).

remove_trace(trace_id, update=False)

Remove the specified trace.

Parameters:

• trace_id – the identifier returned by add_trace()
• update – regenerate the plot script?

reset_options()

Set global plot properties back to defaults.

run(interactive=True)

Execute the generated plot script.

Parameters:interactive – If true, execute the .interactive script instead.

set_cblabel(val=None)

Set label for the z/color axis.

set_export_format(val=None)

Set the desired export format (png, pdf, etc.) for generating an image of the plot. Call get_export_formats() to see which formats your template supports.

set_fontsize(val=None)

Set the “base” font size for axis labels etc. Templates usually scale this to a smaller value for ticks etc.

set_grid(val=True)

Show grid lines.

set_height(val=600)

Set plot height in pixels.

set_legend(val=True)

Enable/disable legend.

set_other_options(val={})

Pass other template-specific plot-level options (as a dictionary).

set_show_on_screen(val=True)

Shown the output on screen (as opposed to only exporting to PNG/EPS/…).

Calling this does not automatically execute the plot script. (Do it using run() or directly from a shell.)

set_title(val=None)

Set the title of the plot window.

set_width(val=800)

Set plot width in pixels.

set_x2label(val=None)

Set label for the right x axis.

set_x2log(val=False)

Set log scale on the right x axis.

set_x2range(minval=None, maxval=None)

Set the top x axis range, None means auto.

set_x2units(val=1)

Set a scaling factor by which the data is divided before plotting.

set_xlabel(val=None)

Set label for the left x axis.

set_xlog(val=False)

Set log scale on the left x axis.

set_xrange(minval=None, maxval=None)

Set the bottom x axis range, None means auto.

set_xunits(val=1)

Set a scaling factor by which the data is divided before plotting.

set_y2label(val=None)

Set label for the top y axis.

set_y2log(val=False)

Set log scale on the top y axis.

set_y2range(minval=None, maxval=None)

Set the right y axis range, None means auto.

set_y2units(val=1)

Set a scaling factor by which the data is divided before plotting.

set_ylabel(val=None)

Set label for the bottom y axis.

set_ylog(val=False)

Set log scale on the bottom y axis.

set_yrange(minval=None, maxval=None)

Set the left y axis range, None means auto.

set_yunits(val=1)

Set a scaling factor by which the data is divided before plotting.

set_zlabel(val=None)

Set label for the z/color axis.

set_zlog(val=False)

Set log scale on the z/color axis.

set_zrange(minval=None, maxval=None)

Set the z axis range, None means auto.

set_zunits(val=1)

Set a scaling factor by which the data is divided before plotting.

update()

Regenerate the outputs based on the specified template.

update_trace(trace_id, x, y=None, yerr=None, update=False, sort=None)

Update data points of the specified trace.

Parameters:

• trace_id – the identifier returned by add_trace()
• x,y,yerr – see add_trace()
• update – regenerate the plot script?
• sort – sort the values according to ‘x’ or ‘y’

Note: Trace options cannot be updated after the initial add_trace().