PlotDataItem

class pyqtgraph.PlotDataItem(

*args,

**kwargs,

)

PlotDataItem is PyQtGraph’s primary way to plot 2D data.

It provides a unified interface for displaying plot curves, scatter plots, or both. The library’s convenience functions such as pyqtgraph.plot() create PlotDataItem objects.

  o-------------o---------------o---------------o
  ^             ^               ^               ^
point         point           point           point

The scatter plot renders a symbol for each point of the data. The curve connects adjacent points. This is realized by a combination of a ScatterPlotItem and a PlotCurveItem. Although these classes can be used individually, PlotDataItem is the recommended way to interact with them.

PlotDataItem contains methods to transform the original data:

• setDerivativeMode()

• setPhasemapMode()

• setFftMode()

• setLogMode()

It can pre-process large data sets to accelerate plotting:

• setDownsampling()

• setClipToView()

PlotDataItem’s performance is usually sufficient for real-time interaction even for large numbers of points. If you do encounter performance issues, consider the following.

• Use a QPen with width=1. All wider pens cause a loss in performance. This loss can be partially mitigated by using fully opaque colors (alphaF=1.0), solid lines, and no anti-aliasing.

• For scatter plots that use multiple pen or brush settings, passing a list of string representation to symbolPen or symbolBrush creates many internal QPen and QBrush objects. Instead, create the needed QPen and QBrush objects in advance and pass these as a list instead. This lets a smaller number of stored instances be reused.

• If you know that all points in your data set will have numerical, finite values, setSkipFiniteCheck() can disable a check to identify points that require special treatment.

• When passing x and y data to PlotDataItem.setData(), use numpy.ndarray instead of python’s built-in lists.

Bases: GraphicsObject

Parameters:

• *args (tuple, optional) – Arguments representing the x and y data to be drawn. The following are examples for initializing data.

  • PlotDataItem(x, y) - x and y are array_like coordinate values.

  • PlotDataItem(x=x, y=y) - same as above, but using keyword arguments.

  • PlotDataItem(y) - y values only, x is automatically set to np.arange(len(y)).

  • PlotDataItem(np.ndarray((N, 2))) - single numpy.ndarray with shape (N, 2), where x is given by data[:, 0] and y by data[:, 1].

  Data can also be initialized with spot-style, per-point arguments.

  • PlotDataItem(recarray) - numpy.recarray record array with dtype=[('x', float), ('y', float), ...]

  • PlotDataItem(list[dict[str, value]]) - list of dictionaries, where each dictionary provides information for a single point. Dictionaries can include coordinate information associated with the x and y keys.

  • PlotDataItem(dict[str, array_like]) - dictionary of lists, where each key corresponds to a keyword argument, and the associated list or array_like structure specifies a value for each point. All dictionary items must provide the same length of data. x and y keys can be included to specify coordinates.

  When using spot-style arguments, it is always possible to give coordinate data separately through the x and y keyword arguments.

• **kwargs (dict, optional) – The supported keyword arguments can be grouped into several categories:

  Point Style Keyword Arguments, see ScatterPlotItem.setData for more information.

  Property	Description
  symbol	str, QPainterPath, list of str or QPainterPath, or None, default None The symbol to use for drawing points, or a list specifying a symbol for each point. If used, str needs to be a string that ScatterPlotItem will recognize. None disables the scatter plot.
  symbolPen	QPen, or arguments accepted by mkPen, list of QPen, or arguments to mkPen, or None, default (200, 200, 200) Outline pen for drawing points, or a list specifying a pen for each point.
  symbolBrush	QBrush, or arguments accepted by mkBrush, or list of QBrush or arguments to mkBrush default (50, 50, 150) Brush for filling points, or a list specifying a brush for each point.
  symbolSize	int or list[int], default 10 Diameter of the symbols, or array-like list of diameters. Diameter is either in pixels or data-space coordinates depending on the value of pxMode.
  pxMode	bool, default True If True, the symbolSize represents the diameter in pixels. If False, the symbolSize represents the diameter in data coordinates.

  Line Style Keyword Arguments

  Property	Description
  connect	{ 'auto', 'finite', 'all', 'pairs', (N,) ndarray }, default 'auto' Normally, the curve connects each point in sequence. Any non-finite, non-plottable values such as NaN result in a gap. The connect argument modifies this behavior. 'finite' and 'auto' both give the normal behavior. The default auto mode enables PlotDataItem to avoid some repeated tests for non-finite values in PlotCurveItem. 'all' - ignores any non-finite values to plot an uninterrupted curve. 'pairs' - generates one line segment for each successive pair of points. ndarray - Individual connections can be specified by an array of length N, matching the number of points. After casting to Boolean, a value of True causes the respective point to be connected to the next.
  stepMode	{ 'left', 'right', 'center' } or None, default None If specified and not None, a stepped curve is drawn. 'left'- the specified points each describe the left edge of a step. 'right'- the specified points each describe the right edge of a step. 'center'- the x coordinates specify the location of the step boundaries. This mode is commonly used for histograms. Note that it requires an additional x value, such that len(x) = len(y) + 1. None - Render the curve normally, and not as a step curve.
  pen	QPen, arguments accepted by mkPen, or None, default is a 1px thick solid line of color (200, 200, 200) Pen for drawing the lines between points. Use None to disable line drawing.
  shadowPen	QPen, arguments accepted by mkPen, or None, default None Pen for drawing a secondary line behind the primary line. Typically used for highlighting or to increase contrast when drawing over background elements.
  fillLevel	float or None, default None If set, the area between the curve and the value of fillLevel is filled. Use None to disable.
  fillBrush	QBrush, None or args accepted by mkBrush, default None Brush used to fill the area specified by fillLevel.
  fillOutline	bool, default False True draws an outline surrounding the area specified by fillLevel, using the plot’s pen and shadowPen.

  Optimization Keyword Arguments

  Property	Description
  useCache	bool, default True Generated point graphics of the scatter plot are cached to improve performance. Setting this to False can improve image quality in some situations.
  antialias	bool, default inherited from pyqtgraph.getConfigOption('antialias') Disabling antialiasing can improve performance. In some cases, in particular when pxMode=True, points will be rendered with antialiasing regardless of this setting.
  autoDownsample	bool, default False Resample the data before plotting to avoid plotting multiple line segments per pixel. This can improve performance when viewing very high-density data, but increases initial overhead and memory usage. See setDownsampling() for more information.
  downsample	int, default 1 Resample the data before plotting, reducing the number of displayed elements by the specified factor. See setDownsampling() for more information.
  downsampleMethod	str, default 'peak' Method for downsampling data. See setDownsampling() for more information.
  clipToView	bool, default False Clip the data to only the visible range on the x-axis. See setClipToView() for more information.
  dynamicRangeLimit	float, default 1e6 Limit off-screen y positions of data points. None disables the limiting. This can increase performance but may cause plots to disappear at high levels of magnification. See setDynamicRangeLimit() for more information.
  dynamicRangeHyst	float, default 3.0 Permit vertical zoom to change up to the given hysteresis factor before the limit calculation is repeated. See setDynamicRangeLimit() for more information.
  skipFiniteCheck	bool, default False If True, the special handling of non-finite values such as NaN in PlotCurveItem is skipped. This speeds up the plot, but creates error or causes the plotting to fail entirely if any such values are present. If connect='auto', PlotDataItem manages the check and this item will be overridden.

  Meta Keyword Arguments

  Property	Description
  name	str or None, default None Name of item for use in the plot legend.

Variables:

• curve (PlotCurveItem) – The underlying Graphics Object used to represent the curve.

• scatter (ScatterPlotItem) – The underlying Graphics Object used to the points along the curve.

• xData (numpy.ndarray or None) – The numpy array representing x-axis data. None if no data has been added.

• yData (numpy.ndarray or None) – The numpy array representing y-axis data. None if no data has been added.

Signals:

• sigPlotChanged (Signal) – Emits when the data in this item is updated.

• sigClicked (Signal) – Emits when the item is clicked. This signal sends the MouseClickEvent.

• sigPointsClicked (Signal) – Emits when a plot point is clicked. Sends the list of points under the mouse, as well as the MouseClickEvent.

• sigPointsHovered (Signal) – Emits when a plot point is hovered over. Sends the list of points under the mouse, as well as the HoverEvent.

See also

arrayToQPath()

Function used to convert numpy.ndarray to QPainterPath.

Notes

The fastest performance results for drawing lines that have a QPen width of 1 pixel. If drawing a 1 pixel thick line, PyQtGraph converts the x and y data to a QPainterPath that is rendered.

The render performance of QPainterPath when using a QPen that has a width greater than 1 is quite poor, but PyQtGraph can fall back to constructing an array of QLine objects representing each line segment. Using QPainter.drawLines, PyQtGraph is able to draw lines with thickness greater than 1 pixel with a smaller performance penalty.

For the QPainter.drawLines method to work, some other factors need to be present.

• pen.style() == QtCore.Qt.PenStyle.SolidLine

• pen.isSolid() is True

• pen.color().alphaF() == 1.0

• pyqtgraph.getConfigOption('antialias') is False

If using lines with a thickness greater than 4 pixel, the QPen instance will be modified such that pen.capStyle() == QtCore.Qt.PenCapStyle.RoundCap. There is a small additional performance penalty with this change.

curveClickable() → bool

Get the attribute if the curve is clickable.

Returns:

Return if the curve is set to be clickable.

Return type:

bool

dataBounds(

ax: int,

frac: float = 1.0,

orthoRange: tuple[float, float] | None = None,

) → tuple[float, float] | tuple[None, None]

Get the range occupied by the data (along a specific axis) for this item.

This method is called by ViewBox when auto-scrolling.

Parameters:

• ax ({ 0, 1 }) – The axis for which to return this items data range. * 0 - x-axis * 1 - y-axis

• frac (float, default 1.0) – Specifies the fraction of the total data range to return. By default, the entire range is returned. This allows the ViewBox to ignore large spikes in the data when auto-scrolling.

• orthoRange (tuple of float, float or None, optional, default None) – Specify that only the data within the given range (orthogonal to ax), should be measured when returning the data range. For example, a ViewBox might ask what is the y-range of all data with x-values between the specifies (min, max) range.

Return type:

tuple[float, float] | tuple[None, None]

Returns:

• min (float or None) – The minimum end of the range that the data occupies along the specified axis. None if there is no data.

• max (float or None) – The maximum end of the range that the data occupies along the specified axis. None if there is no data.

dataRect() → QRectF | None

The bounding rectangle for the full set of data.

Returns:

Will return None if there is no data or if all values (x or y) are NaN.

Return type:

QRectF or None

getData() → tuple[None, None] | tuple[ndarray, ndarray]

Get a representation of the data displayed on screen.

Return type:

tuple[None, None] | tuple[ndarray, ndarray]

Returns:

• xData (numpy.ndarray or None) – The x-axis data, after mapping and data reduction if present or None.

• yData (numpy.ndarray or None) – The y-axis data, after mapping and data reduction if present or None.

See also

getOriginalDataset()

This method returns the original data provided to PlotDataItem instead.

getOriginalDataset() → tuple[None, None] | tuple[ndarray, ndarray]

Get the numpy array representation of the data provided to PlotDataItem.

Return type:

tuple[None, None] | tuple[ndarray, ndarray]

Returns:

• xData (numpy.ndarray or None) – Representation of the original x-axis data.

• yData (numpy.ndarray or None) – Representation of the original y-axis data.

See also

getData()

This method returns the transformed data displayed on the screen instead.

name() → str | None

Get the name attribute if set.

Returns:

The name that represents this item in the legend.

Return type:

str or None

pixelPadding() → int

Get the size (in pixels) that this item might draw beyond the data.

The size of scatter plot symbols or width of the line plot make the displayed image extend further than the extend of the raw data.

Returns:

The padding size in pixels that this item may draw beyond the values returned by dataBounds(). This method is called by ViewBox when auto-scaling.

Return type:

int

setAlpha(

alpha: float,

auto: bool,

)

Set the opacity of the item to the value passed in.

Parameters:

• alpha (float) – Value passed to setOpacity.

• auto (bool) – Receives the autoAlpha value from a parent PlotItem, but has no function within PlotDataItem itself.

See also

QGraphicsItem.setOpacity

This is the Qt method that the value is relayed to.

setBrush(

*args,

**kwargs,

)

An alias to setFillBrush().

Parameters:

• *args (tuple) – QBrush, or parameters for a QBrush constructed by mkBrush. Also accepts a color specifier understood by mkColor.

• **kwargs (dict) – Alternative specification of arguments directed to mkBrush.

setClipToView(

state: bool,

)

Clip the displayed data to the visible range of the x-axis.

This setting can result in significant performance improvements.

Parameters:

state (bool) – Enable clipping the displayed data set to the visible x-axis range.

setCurveClickable(

state: bool,

width: int | None = None,

)

Set the attribute for the curve being clickable.

Parameters:

• state (bool) – Set the curve to be clickable.

• width (int) – The distance tolerance margin in pixels to recognize the mouse click.

setData(

*args,

**kwargs,

)

Clear any data displayed by this item and display new data.

Parameters:

• *args (tuple) – See PlotDataItem description for supported arguments.

• **kwargs (dict) – See PlotDataItem description for supported arguments.

Raises:

TypeError – Raised when an invalid type was passed in for x or y data.

See also

PlotDataItem

The arguments accepted by setData() are the same used during initialization, and are listed in the opening section.

arrayToQPath()

Explains the constructions of the draw paths.

setDerivativeMode(

state: bool,

)

Enable derivative mode.

In derivative mode, the data is mapped according to y_mapped = dy / dx, with dx and dy representing the difference between adjacent x and y values.

Parameters:

state (bool) – Enable derivative mode.

setDownsampling(

ds: int | None = None,

auto: bool | None = None,

method: str = 'peak',

)

Set the downsampling mode.

Downsampling reduces the number of samples drawn to increase performance.

Parameters:

• ds (int or None, default None) – Reduce the number of displayed data points by a factor N=ds. To disable, set ds=1.

• auto (bool or None, default None) – If True, automatically pick ds based on visible range.

• method ({'subsample', 'mean', 'peak'}, default 'peak') – Specify the method of the downsampling calculation.

  • subsample - Downsample by taking the first of N samples. This method is the fastest, but least accurate.

  • mean - Downsample by taking the mean of N samples.

  • peak - Downsample by drawing a saw wave that follows the min and max of the original data. This method produces the best visual representation of the data but is slower.

setDynamicRangeLimit(

limit: float | None = 1000000.0,

hysteresis: float = 3.0,

)

Limit the off-screen positions of data points at large magnification.

This is intended to work around an upstream Qt issue: When zoomed closely into plots with a much larger range of data, plots can fail to display entirely because they are incorrectly determined to be off-screen. The dynamic range limiting avoids this error by repositioning far-off points. At default settings, points are restricted to ±10⁶ times the viewport height.

Parameters:

• limit (float or None, default 1e+06) – Any data outside the range of limit * hysteresis will be constrained to the limit value. All values are relative to the viewport height. None disables the check for a minimal increase in performance.

• hysteresis (float, default 3.0) – Hysteresis factor that controls how much change in zoom level (in terms of the visible y-axis range) is allowed before recalculating.

Notes

See pyqtgraph/pyqtgraph#1676 for an example of the issue this method addresses.

setFftMode(

state: bool,

)

Enable FFT mode.

FFT mode enables mapping the data by a fast Fourier transform. If the x values are not equidistant, the data set is resampled at equal intervals.

Parameters:

state (bool) – To enable or disable FFT mode.

setFillBrush(

*args,

**kwargs,

)

Set the QBrush used to fill the area under the curve.

Use setFillLevel() to enable filling and set the boundary value.

Parameters:

• *args (tuple) – QBrush, or parameters for a QBrush constructed by mkBrush. Also accepts a color specifier understood by mkColor.

• **kwargs (dict) – Alternative specification of arguments directed to mkBrush.

setFillLevel(

level: float | None,

)

Enable filling the area under the curve and set its boundary.

Parameters:

level (float or None) – The value that the fill from the curve is drawn to. Use None to disable the filling.

See also

pyqtgraph.FillBetweenItem

This GraphicsItem creates a filled in region between two curves.

setLogMode(

xState: bool,

yState: bool,

)

Enable log mode per axis.

When the log mode is enabled for the respective axis, a mapping according to mapped = np.log10(value) is applied to the data. For each negative or zero value, this results in a NaN value.

Parameters:

• xState (bool) – Enable log mode on the x-axis.

• yState (bool) – Enable log mode on the y-axis.

setPen(

*args,

**kwargs,

)

Set the primary pen used to draw lines between points.

Parameters:

• *args (tuple or None) – QPen, or parameters for a QPen constructed by mkPen. Use None to disable drawing of lines.

• **kwargs (dict) – Alternative specification of arguments directed to mkPen.

setPhasemapMode(

state: bool,

)

Enable phase map mode.

In phase map mode, the data undergoes a mapping where x_mapped = y and y_mapped = dy / dx, where the numerical derivative of the data is plotted over the original y values.

Parameters:

state (bool) – This enabled phase map mode.

setShadowPen(

*args,

**kwargs,

)

Set the shadow pen used to draw lines between points.

The shadow pen is often used for enhancing contrast or emphasizing data. The line is drawn behind the primary pen and should generally have a greater width than the primary pen.

Parameters:

• *args (tuple or None) – QPen, or parameters for a QPen constructed by mkPen. Use None to disable the shadow pen.

• **kwargs (dict) – Alternative specification of arguments directed to mkPen.

setSkipFiniteCheck(

skipFiniteCheck: bool,

)

Toggle performance option to bypass the finite check.

This option improves performance if it is known that the x and y data passed to PlotDataItem will never contain any non-finite values. If the data does contain any non-finite values (such as NaN or Inf) while this flag is set, unpredictable behavior will occur. The data might not be plotted, or there might be significant performance impact.

In the default connect='auto' mode, PlotDataItem will apply this setting automatically.

Parameters:

skipFiniteCheck (bool) – Skip the numpy.isfinite check for the input arrays.

See also

numpy.isfinite

NumPy function used to identify if there are non-finite values in the x and y data.

arrayToQPath()

Function to create QPainterPath which is rendered on the screen from numpy arrays.

setSymbol(

symbol: str | QPainterPath | list[str | QPainterPath],

)

Set the symbol or symbols for drawing the points.

See pyqtgraph.ScatterPlotItem.setSymbol() for a full list of accepted arguments.

Parameters:

symbol (str or QPainterPath or list) – Symbol to draw as the points. If of type list, it must be the same length as the number of points, and every element must be a recognized string or of type QPainterPath. Use None to disable the scatter plot.

See also

pyqtgraph.ScatterPlotItem.setSymbol()

Recognized symbols are detailed in the description of this method.

setSymbolBrush(

*args,

**kwargs,

)

Set the QBrush used to fill symbols.

Setting a different QBrush per point is not supported by this function.

Parameters:

• *args (tuple) – QBrush, or parameters for a QBrush constructed by mkBrush. Also accepts a color specifier understood by mkColor.

• **kwargs (dict) – Alternative specification of arguments directed to mkBrush.

setSymbolPen(

*args,

**kwargs,

)

Set the QPen used to draw symbols.

Setting a different QPen per point is not supported by this function.

Parameters:

• *args (tuple) – QPen, or parameters for a QPen constructed by mkPen.

• **kwargs (dict) – Alternative specification of arguments directed to mkPen.

setSymbolSize(

size: int,

)

Set the symbol size or sizes.

Parameters:

size (int | list[int]) – Diameter of the symbols, or array-like list of diameters. Diameter is either in pixels or data-space coordinates depending on the value of pxMode.

updateItems(

styleUpdate: bool = True,

)

Update the displayed curve and scatter plot.

This method is called internally to redraw the curve and scatter plot when the data or graphics style has been updated. It is not usally necessary to call this from user code.

Parameters:

styleUpdate (bool, default True) – Indicates if the style was updated in addition to the data.