2.5. TaurusQeTrend - Taurus-Integrated Time-Series Trend Widget

2.5.1. Overview

TaurusQeTrend is a time-series trending widget that bridges the QeTrend canvas with the Taurus SCADA system. It connects to Taurus devices and attributes, receives live data through Taurus events, and appends individual (value, timestamp) points to named trend curves using the underlying QeTrend infrastructure.

The widget uses multiple inheritance from both QeTrend (the C++/Qt time-series plot) and TaurusBaseWidget (the Taurus data-binding base class). When a Taurus attribute fires an event, the internal controller extracts the scalar value and timestamp, then calls QeTrend.CreateOrAppendToTrend() to append a data point to the curve named after the Taurus attribute’s full URI.

Key difference from TaurusQePlot: TaurusQeTrend handles scalar (0D) Taurus attributes, appending one point per event to a named trend curve. TaurusQePlot handles 1D vector attributes, overwriting the entire plot curve with each event. Multiple scalar attributes can trend simultaneously in a single TaurusQeTrend widget, each on its own curve.

The toolbar visibility and per-curve buffer size are configurable on construction. The widget is read-only: it displays data from Taurus but does not support writing values back.

TaurusQeTrend widget (visually identical to QeTrend)

2.5.1.1. Constructor

The constructor signature is

TaurusQeTrend(
    parent: QWidget = None,
    designMode: bool = False,
    taurusparam: object = None,
    toolbar: bool = True,
    buffer_size: int = 65536,
    **kwargs
)

Parameters:

• parent (QWidget, optional) – Parent widget.

• designMode (bool, default False) – Indicates whether the widget is instantiated within Qt Designer.

• taurusparam (object, default None) – Unused Taurus parameter passed through to the base widget.

• toolbar (bool, default True) – If True, the toolbar is shown on construction via ToggleToolbar().

• buffer_size (int, default 65536) – Per-curve data buffer size. Passed to SetQueueSize(). When the number of points on a curve exceeds this limit, the oldest samples are evicted automatically.

Example:

from taurus.qt.qtgui.application import TaurusApplication
from cut.wdglib.taurus.plot.taurusqetrend import TaurusQeTrend

app = TaurusApplication()
trend = TaurusQeTrend(buffer_size=10000)
trend.model = "cii.oldb:/cut/demoservice/instance1/double-scalar-sin"
trend.show()
app.exec_()

2.5.1.2. Inheritance Hierarchy

TaurusQeTrend uses multiple inheritance, combining the QeTrend canvas path with the Taurus data-binding path:

2.5.2. Qt Properties

TaurusQeTrend defines four Qt properties with associated getter, setter, and resetter methods.

2.5.2.1. model

cut.wdglib.taurus.plot.taurusqetrend.model

The unique URI string (or comma-separated list of URIs) representing the Taurus model(s) the widget will read data from. Accepts a single Taurus string or a list of strings. When a string is passed it is split on commas and stripped automatically.

Setting model forces the widget to rebuild its internal controller.

Access functions:

• TaurusBaseWidget.getModel()

• setModel()

• TaurusBaseWidget.resetModel()

Example:

trend.model = "cii.oldb:/cut/demoservice/instance1/double-scalar-sin"
trend.model = ["cii.oldb:/cut/demoservice/instance1/double-scalar-sin", "cii.oldb:/cut/demoservice/instance1/double-scalar-cos"]

cut.wdglib.taurus.plot.taurusqetrend.setModel(m, key=MLIST) → None

Setter for the model property. Accepts a string, a list of strings, or a single Taurus model object. Resets the internal controller so the new model type is handled correctly.

Parameters:

• m – Model URI string, comma-separated string, or list of URIs.

• key – Model key (defaults to MLIST).

2.5.2.2. modelIndex

cut.wdglib.taurus.plot.taurusqetrend.modelIndex

The index expression inside the model value that should be displayed. Stored as a string; internally evaluated and converted to a tuple for array indexing.

Access functions:

• getModelIndex()

• setModelIndex()

• resetModelIndex()

Example:

trend.modelIndex = "(0,)"    # Index into an array
trend.modelIndex = ""        # Reset to None

cut.wdglib.taurus.plot.taurusqetrend.getModelIndex() → str

Return the string representation of the current model index.

Returns:

The model index expression as a string.

cut.wdglib.taurus.plot.taurusqetrend.setModelIndex(modelIndex: str) → None

Parse and apply a model index expression. The value is evaluated via Python’s eval() and must resolve to a sequence (list or tuple). A single integer is automatically wrapped in a tuple. Triggers controller update.

Parameters:

modelIndex – String expression, e.g. "(0,)" or "[1, 2]".

Note

The source code references Sequence from collections.abc without importing it. Calling setModelIndex() with a non-empty value may raise a NameError at runtime.

cut.wdglib.taurus.plot.taurusqetrend.resetModelIndex() → None

Reset the model index to the default value of None.

cut.wdglib.taurus.plot.taurusqetrend.getModelIndexValue() → tuple

Return the internal parsed model index value as a tuple, or None.

2.5.2.3. fgRole

cut.wdglib.taurus.plot.taurusqetrend.fgRole

The foreground role, controlling what value text is displayed on the widget. Valid values are:

• "value" – display the read value

• "w_value" – display the write value

• None – display no value text

Default: "value".

Access functions:

• getFgRole()

• setFgRole()

• resetFgRole()

cut.wdglib.taurus.plot.taurusqetrend.getFgRole() → str

Returns:

The current foreground role string.

cut.wdglib.taurus.plot.taurusqetrend.setFgRole(fgRole: str) → None

Set the foreground role. The value is lowercased and the controller is updated.

Parameters:

fgRole – One of "value", "w_value", or None.

cut.wdglib.taurus.plot.taurusqetrend.resetFgRole() → None

Reset the foreground role to "value".

2.5.2.4. bgRole

cut.wdglib.taurus.plot.taurusqetrend.bgRole

The background role, controlling the widget’s background color based on model state. Valid values are:

• "quality" – color based on Taurus attribute quality

• "state" – color based on Taurus device state

• None – no automatic background update

Default: "quality".

Access functions:

• getBgRole()

• setBgRole()

• resetBgRole()

cut.wdglib.taurus.plot.taurusqetrend.getBgRole() → str

Returns:

The current background role string.

cut.wdglib.taurus.plot.taurusqetrend.setBgRole(bgRole: str) → None

Set the background role. The value is lowercased and the controller is updated.

Parameters:

bgRole – One of "quality", "state", or None.

cut.wdglib.taurus.plot.taurusqetrend.resetBgRole() → None

Reset the background role to "quality".

2.5.3. Methods

2.5.3.1. Taurus Integration

cut.wdglib.taurus.plot.taurusqetrend.handleEvent(evt_src, evt_type, evt_value) → None

Receives a Taurus event and delegates it to the internal controller. The controller identifies which model triggered the event, extracts the scalar value and timestamp, and calls CreateOrAppendToTrend() to append a point to the appropriate trend curve.

cut.wdglib.taurus.plot.taurusqetrend.controller() → TaurusBaseController

Return the internal controller object, creating it lazily on first access. The controller type depends on the model type:

• TaurusModelType.Attribute -> _TaurusQeTrendControllerAttribute

• TaurusModelType.Configuration -> _TaurusQeTrendControllerConfiguration

• Other/unknown -> _TaurusQeTrendController

The controller handles event routing, data extraction, and foreground/ background updates.

Returns:

The active TaurusBaseController instance.

cut.wdglib.taurus.plot.taurusqetrend.isReadOnly() → bool

Returns True. TaurusQeTrend is a display-only widget and does not support writing data back to Taurus models.

Returns:

Always True.

cut.wdglib.taurus.plot.taurusqetrend.getModelObj(key=MLIST) → object

Return the Taurus model object associated with the given key, or None if no model is associated.

Parameters:

key – Model key (defaults to MLIST).

Returns:

The Taurus model object.

cut.wdglib.taurus.plot.taurusqetrend.getModelObjDict() → dict

Return the dictionary of all currently handled Taurus models, mapping keys to their model objects.

Returns:

Dictionary of key-to-model-object mappings.

cut.wdglib.taurus.plot.taurusqetrend.getModelType(key=MLIST) → TaurusElementType

Return the type of the current Taurus model (e.g., Attribute, Configuration, Command, Unknown). Delegates to the base class with the MLIST key.

2.5.3.2. Inherited from QeTrend

TaurusQeTrend inherits the full QeTrend trending API. See QeTrend - Time-Series Trend Widget for the complete reference. The inherited methods include:

• Data loading: CreateOrAppendToTrend(), ClearCurves()

• Queue management: GetQueueSize(), SetQueueSize(), ResetQueueSize()

• Toolbar: ToggleToolbar(), SetMainWindowForToolbar()

• Plot style: on_actionLine_Plot_triggered(), on_actionScatter_Plot_triggered()

• Zoom: on_actionQePlotZoom_In_triggered(), on_actionQePlotZoom_Out_triggered(), on_actionQePlotZoom_Reset_triggered()

• Y-axis scale: on_actionYAxis_Linear_triggered(), on_actionYAxis_Log_triggered(), on_actionYAxis_Square_Root_triggered()

• Export: on_actionExport_triggered()

2.5.3.3. Tend-Specific API Stubs

The following methods are declared on TaurusQeTrend but have no implementation. They are intended for future functionality.

cut.wdglib.taurus.plot.taurusqetrend.setXAxisMode(mode: str) → None

Intended to configure the X-axis display mode. Documented modes are:

• "n" – regular axis

• "e" – event number

• "t" – absolute time/date axis

• "d" – delta time axis

Currently unimplemented. Does nothing.

Parameters:

mode – Unused.

cut.wdglib.taurus.plot.taurusqetrend.setMaxDataBufferSize(max_buffer_size: int) → None

Intended to set the maximum number of values per trend curve. When the limit is reached, the oldest values are discarded. Currently unimplemented. Does nothing.

Note

This method is defined twice in the source code. The first definition (line 450) is missing self and references self in its body, making it broken. The second definition (line 465) is a stub with pass. The first definition shadows the second.

Parameters:

max_buffer_size – Unused.

cut.wdglib.taurus.plot.taurusqetrend.setForcedReadingPeriod(period: int) → None

Intended to force re-reading of Taurus attributes every period milliseconds. Currently unimplemented. Does nothing.

Note

This method is missing the self parameter in the source code. Calling it as an instance method will raise a TypeError.

Parameters:

period – Unused.

cut.wdglib.taurus.plot.taurusqetrend.addModels(names) → None

Intended to add additional Taurus model names to the widget. Currently unimplemented. Does nothing.

Parameters:

names – Unused.

2.5.4. Controller Architecture

The module defines several internal controller classes that mediate between Taurus events and the QeTrend canvas:

• ``_TaurusQeTrendController`` – Base controller. Routes events by model source key. On scalar (DataFormat._0D) data, extracts the value (using .magnitude if available) and the event timestamp, then calls widget.CreateOrAppendToTrend(value, timestamp, name) where name is the Taurus attribute’s full URI. Ignores vector and matrix data.

• ``_TaurusQeTrendControllerAttribute`` – Specialized for TaurusModelType.Attribute. Extends the base controller with TaurusVectorAttributeControllerHelper to properly extract vector magnitudes from Taurus attribute value objects.

• ``_TaurusQeTrendControllerConfiguration`` – Specialized for TaurusModelType.Configuration. Extends the base controller with TaurusConfigurationControllerHelper.

The Controller() factory function selects the appropriate controller class based on the model type via the _CONTROLLER_MAP dictionary.

2.5.4.1. Data Flow

When a Taurus attribute fires an event, the following sequence occurs:

1. TaurusQeTrend.handleEvent() receives the event and delegates to the controller.

2. The controller’s handleEvent() identifies the triggering model by key.

3. controller.update(key) is called, which invokes _updateForeground().

4. _updateForeground() checks data format: only DataFormat._0D (scalar) data is trended. Vector and matrix data are ignored.

5. widget.CreateOrAppendToTrend(value, valueObj.time.totime(), name) appends a (timestamp, value) point to a curve named after the Taurus attribute’s full URI. If the curve does not exist, it is created. If it exists, the new point is appended. The per-curve queue size limits retained samples.

2.5.5. Standalone Launcher

The taurus trend command launches a standalone trending application window. With the cut.wdglib.taurus.plot package installed, cuttrend is registered as an alternative implementation for the taurus trend subcommand. Unlike taurus plot which stacks one widget per model, the cuttrend implementation assigns all models to a single widget, resulting in multiple named curves within one trend canvas.

Single attribute:

taurus trend cii.oldb:/cut/demoservice/instance1/double-scalar-sin

Multiple attributes:

taurus trend \
    cii.oldb:/cut/demoservice/instance1/double-scalar-sin \
    cii.oldb:/cut/demoservice/instance1/double-scalar-cos

Demo mode:

taurus trend --demo

2.5.6. Example Usage

Connecting to a scalar Taurus attribute:

from taurus.qt.qtgui.application import TaurusApplication
from cut.wdglib.taurus.plot.taurusqetrend import TaurusQeTrend

app = TaurusApplication()
trend = TaurusQeTrend(buffer_size=10000)
trend.model = "cii.oldb:/cut/demoservice/instance1/double-scalar-sin"
trend.fgRole = "value"
trend.bgRole = "quality"
trend.show()
app.exec_()

Multiple attributes on one trend canvas:

from taurus.qt.qtgui.application import TaurusApplication
from cut.wdglib.taurus.plot.taurusqetrend import TaurusQeTrend

app = TaurusApplication()
trend = TaurusQeTrend(buffer_size=5000)
trend.model = [
    "cii.oldb:/cut/demoservice/instance1/double-scalar-sin",
    "cii.oldb:/cut/demoservice/instance1/double-scalar-cos",
]
trend.show()
app.exec_()

Using the taurus trend command:

taurus trend cii.oldb:/cut/demoservice/instance1/double-scalar-sin

Programmatically controlling trend appearance:

from cut.wdglib.taurus.plot.taurusqetrend import TaurusQeTrend

trend = TaurusQeTrend(buffer_size=2000)
trend.model = ["eval:rand()", "eval:1+rand(2)"]
trend.fgRole = "value"
trend.bgRole = "state"

# Switch to scatter mode
trend.on_actionScatter_Plot_triggered(True)

# Monitor queue size changes
trend.QueueSizeChanged.connect(lambda v: print(f"Queue size: {v}"))

2.5.7. Notes

• TaurusQeTrend is read-only. It displays data from Taurus models but does not support writing values back to devices.

• Only scalar data (DataFormat._0D) is trended. Vector attributes (DataFormat._1D) and matrix data are silently ignored by the controller’s _updateForeground().

• Unlike TaurusQePlot which replaces the curve on each event, TaurusQeTrend appends one data point per event to a named curve. Multiple attributes produce multiple named curves within the same widget.

• The curve name for each incoming attribute is set to the Taurus attribute’s full URI (valueObj.getFullName()).

• The toolbar is shown by default on construction. Set toolbar=False in the constructor to suppress it.

• The default per-curve buffer size is 65536 points. Configure via the buffer_size constructor parameter or by calling SetQueueSize().

• setModelIndex() has a bug: it references Sequence from collections.abc without importing it, which causes a NameError when called with a non-empty index expression.

• setForcedReadingPeriod() is missing the self parameter in its definition. Calling it as an instance method will raise a TypeError.

• setMaxDataBufferSize() is defined twice in the source. The first definition (as a static method) references self in its body and is broken. The second definition is a stub. The first shadows the second.

• addModels(), setXAxisMode(), and setForcedReadingPeriod() are all unimplemented stubs.

• Several source docstrings have copy-paste errors (e.g., setModelIndex says “Getter” in the docstring, and resetModelIndex references bgRole instead of modelIndex).

• The numpy and datetime imports at the top of the module are unused.

• The bgRole and fgRole values are lowercased automatically on set.

• When the model is set from a UI source as a comma-separated string, it is automatically split into a list.

• The widget is registered as a Qt Designer plugin in the “Taurus Display” group with the tool tip “Trending tool based on QeTrend.”

• PDF export writes to ~/qeplot-<timestamp>.pdf. There is no way to override the output path from Python.

• Mouse interaction is built-in from QePlotBase: left-click drag for panning, mouse wheel for zooming, with a tracker tooltip on the canvas.

• The window_name parameter in trend_main() defaults to "Taurus QePlot" (a copy-paste from the plot launcher) and is unused; the actual window title is hardcoded to "Taurus QeTrend".