.. currentmodule:: taurus.qt.qtgui.plot

.. _taurusplot_ui:

Plotting with Taurus
====================

.. note:: Some details in this page originate from the legacy plotting widgets
          and may not exactly match the current ``taurus_pyqtgraph`` interface.

The standard way for Taurus applications to show one-dimensional data is by
using a :class:`TaurusPlot` widget.

:class:`TaurusPlot` is shown as an area with X and Y axes where curves (data
sets) are plotted. It may also show a legend.

.. figure:: /_static/taurusplot04.png
   :align: center

A :class:`TaurusPlot` does more than displaying a plot. It also provides tools
for interacting with the displayed data and configuring its representation.

.. note:: The features described here are available *by default* in all
          TaurusPlot widgets, but certain GUIs may choose to disable some of
          these features.

Two Y scales
------------

A :class:`TaurusPlot` has an X axis and one or two Y axes (left and right, also
called Y1 and Y2, respectively). Multiple curves can be displayed
simultaneously and each one is associated with either Y1 or Y2.

By default, :class:`TaurusPlot` only shows a legend when more than one curve is
displayed.

The axis associated with a curve can be changed from the plot configuration.
See :ref:`howto-plotting` for task-oriented instructions on configuring a plot.

.. _taurusplottime:

Date/time support
-----------------

In some applications, the values of the X axis are interpreted as date/time
values. In this mode, the values of the abscissas must be valid epoch numbers,
i.e. seconds since the UNIX epoch.

TaurusPlot interprets such values and displays formatted dates and times instead
of the epoch number:

.. image:: /_static/taurusplot-timesupport01.png

When launching TaurusPlot from the command line, this mode can be selected with
the ``-x t`` option. See :ref:`howto-plotting` for more information about
using TaurusPlot.

Plotting backends
-----------------

Taurus uses different plotting backends for its plotting widgets:

- plotpy_ provides :class:`TaurusImageDialog` and
  :class:`TaurusTrend2DDialog`, implemented in
  :mod:`taurus.qt.qtgui.extra_plotpy`.
- pyqtgraph_ is used by the :class:`TaurusPlot` and :class:`TaurusTrend`
  implementations provided by the taurus_pyqtgraph_ plugin. This replaced the
  PyQwt5-based implementations that were available in Taurus versions before
  5 (see TEP17_).

For applications using the taurus_pyqtgraph_ plugin, Taurus functionality is
intended to extend regular pyqtgraph_ widgets. The pyqtgraph documentation and
examples are therefore useful together with the Taurus-specific plugin
examples.

.. _plotpy: https://plotpy.readthedocs.io/en/latest/
.. _pyqtgraph: https://www.pyqtgraph.org/
.. _taurus_pyqtgraph: https://gitlab.com/taurus-org/taurus_pyqtgraph
.. _TEP17: https://gitlab.com/taurus-org/taurus/-/blob/develop/doc/source/tep/TEP17.md