plotpy.builder

The builder module provides a builder singleton class used to simplify the creation of plot items.

Example

Before creating any widget, a QApplication must be instantiated (that is a Qt internal requirement):

>>> import guidata
>>> app = guidata.qapplication()

that is mostly equivalent to the following (the only difference is that the guidata helper function also installs the Qt translation corresponding to the system locale):

>>> from PyQt4.QtGui import QApplication
>>> app = QApplication([])

now that a QApplication object exists, we may create the plotting widget:

>>> from plotpy.plot import ImageWidget
>>> widget = ImageWidget()

create curves, images, histograms, etc. and attach them to the plot:

>>> from plotpy.builder import make
>>> curve = make.mcure(x, y, 'r+')
>>> image = make.image(data)
>>> hist = make.histogram(data, 100)
>>> for item in (curve, image, hist):
...     widget.plot.add_item()

and then show the widget to screen:

>>> widget.show()
>>> app.exec_()

Reference

class plotpy.builder.PlotItemBuilder

This is just a bare class used to regroup a set of factory functions in a single object

gridparam(background=None, major_enabled=None, minor_enabled=None, major_style=None, minor_style=None)

Make plotpy.styles.GridParam instance

• background = canvas background color
• major_enabled = tuple (major_xenabled, major_yenabled)
• minor_enabled = tuple (minor_xenabled, minor_yenabled)
• major_style = tuple (major_xstyle, major_ystyle)
• minor_style = tuple (minor_xstyle, minor_ystyle)

Style: tuple (style, color, width)

grid(background=None, major_enabled=None, minor_enabled=None, major_style=None, minor_style=None)

Make a grid plot item (plotpy.curve.GridItem object)

• background = canvas background color
• major_enabled = tuple (major_xenabled, major_yenabled)
• minor_enabled = tuple (minor_xenabled, minor_yenabled)
• major_style = tuple (major_xstyle, major_ystyle)
• minor_style = tuple (minor_xstyle, minor_ystyle)

Style: tuple (style, color, width)

mcurve(*args, **kwargs)

Make a curve plot item based on MATLAB-like syntax (may returns a list of curves if data contains more than one signal) (plotpy.curve.CurveItem object)

Example:

mcurve(x, y, 'r+')

pcurve(x, y, param, xaxis='bottom', yaxis='left')

Make a curve plot item based on a plotpy.styles.CurveParam instance (plotpy.curve.CurveItem object)

Usage:

pcurve(x, y, param)

curve(x, y, title='', color=None, linestyle=None, linewidth=None, marker=None, markersize=None, markerfacecolor=None, markeredgecolor=None, shade=None, curvestyle=None, baseline=None, xaxis='bottom', yaxis='left')

Make a curve plot item from x, y, data (plotpy.curve.CurveItem object)

• x: 1D NumPy array
• y: 1D NumPy array
• color: curve color name
• linestyle: curve line style (MATLAB-like string or “SolidLine”, “DashLine”, “DotLine”, “DashDotLine”, “DashDotDotLine”, “NoPen”)
• linewidth: line width (pixels)
• marker: marker shape (MATLAB-like string or “Cross”, “Ellipse”, “Star1”, “XCross”, “Rect”, “Diamond”, “UTriangle”, “DTriangle”, “RTriangle”, “LTriangle”, “Star2”, “NoSymbol”)
• markersize: marker size (pixels)
• markerfacecolor: marker face color name
• markeredgecolor: marker edge color name
• shade: 0 <= float <= 1 (curve shade)
• curvestyle: “Lines”, “Sticks”, “Steps”, “Dots”, “NoCurve”
• baseline (float: default=0.0): the baseline is needed for filling the curve with a brush or the Sticks drawing style.
• xaxis, yaxis: X/Y axes bound to curve

Example:

curve(x, y, marker='Ellipse', markerfacecolor='#ffffff')

which is equivalent to (MATLAB-style support):

curve(x, y, marker='o', markerfacecolor='w')

merror(*args, **kwargs)

Make an errorbar curve plot item based on MATLAB-like syntax (plotpy.curve.ErrorBarCurveItem object)

Example:

mcurve(x, y, 'r+')

perror(x, y, dx, dy, curveparam, errorbarparam, xaxis='bottom', yaxis='left')

Make an errorbar curve plot item based on a plotpy.styles.ErrorBarParam instance (plotpy.curve.ErrorBarCurveItem object)

• x: 1D NumPy array
• y: 1D NumPy array
• dx: None, or scalar, or 1D NumPy array
• dy: None, or scalar, or 1D NumPy array
• curveparam: plotpy.styles.CurveParam object
• errorbarparam: plotpy.styles.ErrorBarParam object
• xaxis, yaxis: X/Y axes bound to curve

Usage:

perror(x, y, dx, dy, curveparam, errorbarparam)

error(x, y, dx, dy, title='', color=None, linestyle=None, linewidth=None, errorbarwidth=None, errorbarcap=None, errorbarmode=None, errorbaralpha=None, marker=None, markersize=None, markerfacecolor=None, markeredgecolor=None, shade=None, curvestyle=None, baseline=None, xaxis='bottom', yaxis='left')

Make an errorbar curve plot item (plotpy.curve.ErrorBarCurveItem object)

• x: 1D NumPy array
• y: 1D NumPy array
• dx: None, or scalar, or 1D NumPy array
• dy: None, or scalar, or 1D NumPy array
• color: curve color name
• linestyle: curve line style (MATLAB-like string or attribute name from the PyQt4.QtCore.Qt.PenStyle enum (i.e. “SolidLine” “DashLine”, “DotLine”, “DashDotLine”, “DashDotDotLine” or “NoPen”)
• linewidth: line width (pixels)
• marker: marker shape (MATLAB-like string or attribute name from the PyQt4.Qwt5.QwtSymbol.Style enum (i.e. “Cross”, “Ellipse”, “Star1”, “XCross”, “Rect”, “Diamond”, “UTriangle”, “DTriangle”, “RTriangle”, “LTriangle”, “Star2” or “NoSymbol”)
• markersize: marker size (pixels)
• markerfacecolor: marker face color name
• markeredgecolor: marker edge color name
• shade: 0 <= float <= 1 (curve shade)
• curvestyle: attribute name from the PyQt4.Qwt5.QwtPlotCurve.CurveStyle enum (i.e. “Lines”, “Sticks”, “Steps”, “Dots” or “NoCurve”)
• baseline (float: default=0.0): the baseline is needed for filling the curve with a brush or the Sticks drawing style.
• xaxis, yaxis: X/Y axes bound to curve

Example:

error(x, y, None, dy, marker='Ellipse', markerfacecolor='#ffffff')

which is equivalent to (MATLAB-style support):

error(x, y, None, dy, marker='o', markerfacecolor='w')

histogram(data, bins=None, logscale=None, title='', color=None, xaxis='bottom', yaxis='left')

Make 1D Histogram plot item (plotpy.histogram.HistogramItem object)

• data (1D NumPy array)
• bins: number of bins (int)
• logscale: Y-axis scale (bool)

phistogram(data, curveparam, histparam, xaxis='bottom', yaxis='left')

Make 1D histogram plot item (plotpy.histogram.HistogramItem object) based on a plotpy.styles.CurveParam and plotpy.styles.HistogramParam instances

Usage:

phistogram(data, curveparam, histparam)

static compute_bounds(data, pixel_size, center_on)

Return image bounds from pixel_size (scalar or tuple)

image(data=None, filename=None, title=None, alpha_mask=None, alpha=None, background_color=None, colormap=None, xdata=[None, None], ydata=[None, None], pixel_size=None, center_on=None, interpolation='linear', eliminate_outliers=None, xformat='%.1f', yformat='%.1f', zformat='%.1f')

Make an image plot item from data (plotpy.image.ImageItem object or plotpy.image.RGBImageItem object if data has 3 dimensions)

maskedimage(data=None, mask=None, filename=None, title=None, alpha_mask=False, alpha=1.0, xdata=[None, None], ydata=[None, None], pixel_size=None, center_on=None, background_color=None, colormap=None, show_mask=False, fill_value=None, interpolation='linear', eliminate_outliers=None, xformat='%.1f', yformat='%.1f', zformat='%.1f')

Make a masked image plot item from data (plotpy.image.MaskedImageItem object)

rgbimage(data=None, filename=None, title=None, alpha_mask=False, alpha=1.0, xdata=[None, None], ydata=[None, None], pixel_size=None, center_on=None, interpolation='linear')

Make a RGB image plot item from data (plotpy.image.RGBImageItem object)

quadgrid(X, Y, Z, filename=None, title=None, alpha_mask=None, alpha=None, background_color=None, colormap=None, interpolation='linear')

Make a pseudocolor plot item of a 2D array (plotpy.image.QuadGridItem object)

pcolor(*args, **kwargs)

Make a pseudocolor plot item of a 2D array based on MATLAB-like syntax (plotpy.image.QuadGridItem object)

Examples:

pcolor(C)
pcolor(X, Y, C)

trimage(data=None, filename=None, title=None, alpha_mask=None, alpha=None, background_color=None, colormap=None, x0=0.0, y0=0.0, angle=0.0, dx=1.0, dy=1.0, interpolation='linear', eliminate_outliers=None, xformat='%.1f', yformat='%.1f', zformat='%.1f')

Make a transformable image plot item (image with an arbitrary affine transform) (plotpy.image.TrImageItem object)

• data: 2D NumPy array (image pixel data)
• filename: image filename (if data is not specified)
• title: image title (optional)
• x0, y0: position
• angle: angle (radians)
• dx, dy: pixel size along X and Y axes
• interpolation: ‘nearest’, ‘linear’ (default), ‘antialiasing’ (5x5)

xyimage(x, y, data, title=None, alpha_mask=None, alpha=None, background_color=None, colormap=None, interpolation='linear', eliminate_outliers=None, xformat='%.1f', yformat='%.1f', zformat='%.1f')

Make an xyimage plot item (image with non-linear X/Y axes) from data (plotpy.image.XYImageItem object)

• x: 1D NumPy array (or tuple, list: will be converted to array)
• y: 1D NumPy array (or tuple, list: will be converted to array
• data: 2D NumPy array (image pixel data)
• title: image title (optional)
• interpolation: ‘nearest’, ‘linear’ (default), ‘antialiasing’ (5x5)

imagefilter(xmin, xmax, ymin, ymax, imageitem, filter, title=None)

Make a rectangular area image filter plot item (plotpy.image.ImageFilterItem object)

• xmin, xmax, ymin, ymax: filter area bounds
• imageitem: An imageitem instance
• filter: function (x, y, data) –> data

histogram2D(X, Y, NX=None, NY=None, logscale=None, title=None, transparent=None, Z=None, computation=-1, interpolation=0)

Make a 2D Histogram plot item (plotpy.image.Histogram2DItem object)

• X: data (1D array)
• Y: data (1D array)
• NX: Number of bins along x-axis (int)
• NY: Number of bins along y-axis (int)
• logscale: Z-axis scale (bool)
• title: item title (string)
• transparent: enable transparency (bool)

label(text, g, c, anchor, title='')

Make a label plot item (plotpy.label.LabelItem object)

• text: label text (string)
• g: position in plot coordinates (tuple) or relative position (string)
• c: position in canvas coordinates (tuple)
• anchor: anchor position in relative position (string)
• title: label name (optional)

Examples:

make.label("Relative position", (x[0], y[0]), (10, 10), "BR")
make.label("Absolute position", "R", (0,0), "R")

legend(anchor='TR', c=None, restrict_items=None)

Make a legend plot item (plotpy.label.LegendBoxItem or plotpy.label.SelectedLegendBoxItem object)

• anchor: legend position in relative position (string)

• c (optional): position in canvas coordinates (tuple)

• restrict_items (optional):

  • None: all items are shown in legend box
  • []: no item shown
  • [item1, item2]: item1, item2 are shown in legend box

vcursor(x, label=None, constraint_cb=None, movable=True, readonly=False)

Make a vertical cursor plot item

Convenient function to make a vertical marker (plotpy.shapes.Marker object)

hcursor(y, label=None, constraint_cb=None, movable=True, readonly=False)

Make an horizontal cursor plot item

Convenient function to make an horizontal marker (plotpy.shapes.Marker object)

xcursor(x, y, label=None, constraint_cb=None, movable=True, readonly=False)

Make an cross cursor plot item

Convenient function to make an cross marker (plotpy.shapes.Marker object)

marker(position=None, label_cb=None, constraint_cb=None, movable=True, readonly=False, markerstyle=None, markerspacing=None, color=None, linestyle=None, linewidth=None, marker=None, markersize=None, markerfacecolor=None, markeredgecolor=None)

Make a marker plot item (plotpy.shapes.Marker object)

• position: tuple (x, y)
• label_cb: function with two arguments (x, y) returning a string
• constraint_cb: function with two arguments (x, y) returning a tuple (x, y) according to the marker constraint
• movable: if True (default), marker will be movable
• readonly: if False (default), marker can be deleted
• markerstyle: ‘+’, ‘-‘, ‘|’ or None
• markerspacing: spacing between text and marker line
• color: marker color name
• linestyle: marker line style (MATLAB-like string or attribute name from the PyQt4.QtCore.Qt.PenStyle enum (i.e. “SolidLine” “DashLine”, “DotLine”, “DashDotLine”, “DashDotDotLine” or “NoPen”)
• linewidth: line width (pixels)
• marker: marker shape (MATLAB-like string or “Cross”, “Ellipse”, “Star1”, “XCross”, “Rect”, “Diamond”, “UTriangle”, “DTriangle”, “RTriangle”, “LTriangle”, “Star2”, “NoSymbol”)
• markersize: marker size (pixels)
• markerfacecolor: marker face color name
• markeredgecolor: marker edge color name

rectangle(x0, y0, x1, y1, title=None)

Make a rectangle shape plot item (plotpy.shapes.RectangleShape object)

• x0, y0, x1, y1: rectangle coordinates
• title: label name (optional)

ellipse(x0, y0, x1, y1, title=None)

Make an ellipse shape plot item (plotpy.shapes.EllipseShape object)

• x0, y0, x1, y1: ellipse x-axis coordinates
• title: label name (optional)

circle(x0, y0, x1, y1, title=None)

Make a circle shape plot item (plotpy.shapes.EllipseShape object)

• x0, y0, x1, y1: circle diameter coordinates
• title: label name (optional)

segment(x0, y0, x1, y1, title=None)

Make a segment shape plot item (plotpy.shapes.SegmentShape object)

• x0, y0, x1, y1: segment coordinates
• title: label name (optional)

annotated_rectangle(x0, y0, x1, y1, title=None, subtitle=None)

Make an annotated rectangle plot item (plotpy.annotations.AnnotatedRectangle object)

• x0, y0, x1, y1: rectangle coordinates
• title, subtitle: strings

annotated_ellipse(x0, y0, x1, y1, ratio, title=None, subtitle=None)

Make an annotated ellipse plot item (plotpy.annotations.AnnotatedEllipse object)

• x0, y0, x1, y1: ellipse rectangle coordinates
• ratio: ratio between y-axis and x-axis lengths
• title, subtitle: strings

annotated_circle(x0, y0, x1, y1, ratio, title=None, subtitle=None)

Make an annotated circle plot item (plotpy.annotations.AnnotatedCircle object)

• x0, y0, x1, y1: circle diameter coordinates
• title, subtitle: strings

annotated_segment(x0, y0, x1, y1, title=None, subtitle=None)

Make an annotated segment plot item (plotpy.annotations.AnnotatedSegment object)

• x0, y0, x1, y1: segment coordinates
• title, subtitle: strings

info_label(anchor, comps, title=None)

Make an info label plot item (plotpy.label.DataInfoLabel object)

range_info_label(range, anchor, label, function=None, title=None)

Make an info label plot item showing an XRangeSelection object infos (plotpy.label.DataInfoLabel object) (see example: plotpy.tests.computations)

Default function is lambda x, dx: (x, dx).

Example:

x = linspace(-10, 10, 10)
y = sin(sin(sin(x)))
range = make.range(-2, 2)
disp = make.range_info_label(range, 'BL', "x = %.1f ± %.1f cm",
                             lambda x, dx: (x, dx))        

computation(range, anchor, label, curve, function, title=None)

Make a computation label plot item (plotpy.label.DataInfoLabel object) (see example: plotpy.tests.computations)

computations(range, anchor, specs, title=None)

Make computation labels plot item (plotpy.label.DataInfoLabel object) (see example: plotpy.tests.computations)

computation2d(rect, anchor, label, image, function, title=None)

Make a 2D computation label plot item (plotpy.label.RangeComputation2d object) (see example: plotpy.tests.computations)

computations2d(rect, anchor, specs, title=None)

Make 2D computation labels plot item (plotpy.label.RangeComputation2d object) (see example: plotpy.tests.computations)