.. currentmodule:: silx.gui Getting started with plot widgets ================================= This introduction to :mod:`silx.gui.plot` covers the following topics: - `Use silx.gui.plot from the console`_ - `Use silx.gui.plot from a script`_ - `Plot curves in a widget`_ - `Plot images in a widget`_ - `Control plot axes`_ For a complete description of the API, see :mod:`silx.gui.plot`. Use :mod:`silx.gui.plot` from the console ----------------------------------------- From IPython ++++++++++++ To run :mod:`silx.gui.plot` widgets from `IPython `_, IPython must be set to use Qt (and in case of using PyQt4 and Python 2.7, PyQt must be set ti use API version 2, see Explanation_ below). As *silx* is performing some configuration of the Qt binding and `matplotlib `_, the safest way to use *silx* from IPython is to import :mod:`silx.gui.plot` first and then run either `%gui `_ qt or `%pylab `_ qt:: In [1]: from silx.gui.plot import * In [2]: %pylab qt Alternatively, when using Python 2.7 and PyQt4, you can start IPython with the ``QT_API`` environment variable set to ``pyqt``. On Linux and MacOS X, run:: QT_API=pyqt ipython On Windows, run from the command line:: set QT_API=pyqt&&ipython Explanation ........... PyQt4 used from Python 2.x provides 2 incompatible versions of QString and QVariant: - version 1, the legacy which is the default, and - version 2, a more pythonic one, which is the only one supported by *silx*. All other configurations (i.e., PyQt4 on Python 3.x, PySide, PyQt5, IPython QtConsole widget) uses version 2 only or as the default. For more information, see `IPython, PyQt and PySide `_. From Python +++++++++++ The :mod:`silx.sx` package is a convenient module to use silx from the console. It sets-up Qt and provides functions for the main features of silx. >>> from silx import sx Alternatively, you can create a QApplication before using silx widgets: >>> from silx.gui import qt # Import Qt binding and do some set-up >>> qapp = qt.QApplication([]) >>> from silx.gui.plot import * # Import plot widgets and set-up matplotlib .. currentmodule:: silx.sx Plot functions ++++++++++++++ The :mod:`silx.sx` package provides 2 functions to plot curves and images from the (I)Python console in a widget with a set of tools: - :func:`plot`, and - :func:`imshow`. For more features, use widgets directly (see `Plot curves in a widget`_ and `Plot images in a widget`_). Curve: :func:`plot` ................... The following examples must run with a Qt QApplication initialized (see `Use silx.gui.plot from the console`_). First import :mod:`sx` function: >>> from silx import sx >>> import numpy Plot a single curve given some values: >>> values = numpy.random.random(100) >>> plot_1curve = sx.plot(values, title='Random data') Plot a single curve given the x and y values: >>> angles = numpy.linspace(0, numpy.pi, 100) >>> sin_a = numpy.sin(angles) >>> plot_sinus = sx.plot(angles, sin_a, ... xlabel='angle (radian)', ylabel='sin(a)') Plot many curves by giving a 2D array, provided xn, yn arrays: >>> plot_curves = sx.plot(x0, y0, x1, y1, x2, y2, ...) Plot curve with style giving a style string: >>> plot_styled = sx.plot(x0, y0, 'ro-', x1, y1, 'b.') See :func:`plot` for details. Image: :func:`imshow` ..................... This example plot a single image. First, import :mod:`silx.sx`: >>> from silx import sx >>> import numpy >>> data = numpy.random.random(1024 * 1024).reshape(1024, 1024) >>> plt = sx.imshow(data, title='Random data') See :func:`imshow` for more details. Use :mod:`silx.gui.plot` from a script -------------------------------------- A Qt GUI script must have a QApplication initialized before creating widgets: .. code-block:: python from silx.gui import qt [...] qapp = qt.QApplication([]) [...] # Widgets initialisation if __name__ == '__main__': [...] qapp.exec_() Unless a Qt binding has already been loaded, :mod:`silx.gui.qt` uses the first Qt binding it founds by probing in the following order: PyQt5, PyQt4 and finally PySide. If you prefer to choose the Qt binding yourself, import it before importing a module from :mod:`silx.gui`: .. code-block:: python import PySide # Importing PySide will force silx to use it from silx.gui import qt .. warning:: :mod:`silx.gui.plot` widgets are not thread-safe. All calls to :mod:`silx.gui.plot` widgets must be made from the main thread. Plot curves in a widget ----------------------- The :class:`Plot1D` widget provides a plotting area and a toolbar with tools useful for curves such as setting logarithmic scale or defining region of interest. First, create a :class:`Plot1D` widget: .. code-block:: python from silx.gui.plot import Plot1D plot = Plot1D() # Create the plot widget plot.show() # Make the plot widget visible One curve +++++++++ To display a single curve, use the :meth:`.PlotWidget.addCurve` method: .. code-block:: python plot.addCurve(x=(1, 2, 3), y=(3, 2, 1)) # Add a curve with default style When you need to update this curve, call :meth:`.PlotWidget.addCurve` again with the new values to display: .. code-block:: python plot.addCurve(x=(1, 2, 3), y=(1, 2, 3)) # Replace the existing curve To clear the plotting area, call :meth:`.PlotWidget.clear`: .. code-block:: python plot.clear() Multiple curves +++++++++++++++ In order to display multiple curves at the same time, you need to provide a different ``legend`` string for each of them: .. code-block:: python import numpy x = numpy.linspace(-numpy.pi, numpy.pi, 1000) plot.addCurve(x, numpy.sin(x), legend='sinus') plot.addCurve(x, numpy.cos(x), legend='cosinus') plot.addCurve(x, numpy.random.random(len(x)), legend='random') To update a curve, call :meth:`.PlotWidget.addCurve` with the ``legend`` of the curve you want to udpdate. By default, the new curve will keep the same color (and style) as the curve it is updating: .. code-block:: python plot.addCurve(x, numpy.random.random(len(x)) - 1., legend='random') To remove a curve from the plot, call :meth:`.PlotWidget.remove` with the ``legend`` of the curve you want to remove from the plot: .. code-block:: python plot.remove('random') To clear the plotting area, call :meth:`.PlotWidget.clear`: .. code-block:: python plot.clear() Curve style +++++++++++ By default, different curves will automatically use different styles to render, and keep the same style when updated. It is possible to specify the ``color`` of the curve, its ``linewidth`` and ``linestyle`` as well as the ``symbol`` to use as markers for data points (See :meth:`.PlotWidget.addCurve` for more details): .. code-block:: python import numpy x = numpy.linspace(-numpy.pi, numpy.pi, 100) # Curve with a thick dashed line plot.addCurve(x, numpy.sin(x), legend='sinus', linewidth=3, linestyle='--') # Curve with pink markers only plot.addCurve(x, numpy.cos(x), legend='cosinus', color='pink', linestyle=' ', symbol='o') # Curve with green line with square markers plot.addCurve(x, numpy.random.random(len(x)), legend='random', color='green', linestyle='-', symbol='s') Histogram +++++++++ Data can be displayed as an histogram. This must be specified when calling the the addCurve function. (using ``histogram``, See :meth:`.PlotWidget.addCurve` for more details ). Histogram steps can be centered on x values or set at the left or the right of the given x values. .. code-block:: python import numpy x = numpy.arange(0, 20, 1) plot.addCurve(x, x+1, histogram='center', fill=True, color='green') .. note:: You can also give x as edges. For this you must have len(x) = len(y) + 1 Plot images in a widget ----------------------- The :class:`Plot2D` widget provides a plotting area and a toolbar with tools useful for images, such as keeping aspect ratio, changing the colormap or defining a mask. First, create a :class:`Plot2D` widget: .. code-block:: python from silx.gui.plot import Plot2D plot = Plot2D() # Create the plot widget plot.show() # Make the plot widget visible One image +++++++++ To display a single image, use the :meth:`.PlotWidget.addImage` method: .. code-block:: python import numpy data = numpy.random.random(512 * 512).reshape(512, -1) # Create 2D image plot.addImage(data) # Plot the 2D data set with default colormap To update this image, call :meth:`.PlotWidget.addImage` again with the new image to display: .. code-block:: python # Create a RGB image rgb_image = (numpy.random.random(512*512*3) * 255).astype(numpy.uint8) rgb_image.shape = 512, 512, 3 plot.addImage(rgb_image) # Plot the RGB image instead of the previous data To clear the plotting area, call :meth:`.PlotWidget.clear`: .. code-block:: python plot.clear() Origin and scale ++++++++++++++++ :meth:`.PlotWidget.addImage` supports both 2D arrays of data displayed with a colormap and RGB(A) images as 3D arrays of shape (height, width, color channels). When displaying an image, it is possible to specify the ``origin`` and the ``scale`` of the image array in the plot area coordinates: .. code-block:: python data = numpy.random.random(512 * 512).reshape(512, -1) plot.addImage(data, origin=(100, 100), scale=(0.1, 0.1)) When updating an image, if ``origin`` and ``scale`` are not provided, the previous values will be used: .. code-block:: python data = numpy.random.random(512 * 512).reshape(512, -1) plot.addImage(data) # Keep previous origin and scale Colormap ++++++++ A ``colormap`` is described with a :class:`dict` as follows (See :mod:`silx.gui.plot.Plot` for full documentation of the colormap): .. code-block:: python colormap = { 'name': 'gray', # Name of the colormap 'normalization': 'linear', # Either 'linear' or 'log' 'autoscale': True, # True to autoscale colormap to data range, False to use [vmin, vmax] 'vmin': 0.0, # If not autoscale, data value to bind to min of colormap 'vmax': 1.0 # If not autoscale, data value to bind to max of colormap } At least the following colormap names are guaranteed to be available, but any colormap name from `matplotlib `_ (see `Choosing Colormaps `_) should work: - gray - reversed gray - temperature - red - green - blue - viridis - magma - inferno - plasma It is possible to change the default colormap of :meth:`.PlotWidget.addImage` for the plot widget with :meth:`.PlotWidget.setDefaultColormap` (and to get it with :meth:`.PlotWidget.getDefaultColormap`): .. code-block:: python colormap = {'name': 'viridis', 'normalization': 'linear', 'autoscale': True, 'vmin': 0.0, 'vmax': 1.0} plot.setDefaultColormap(colormap) data = numpy.arange(512 * 512.).reshape(512, -1) plot.addImage(data) # Rendered with the default colormap set before It is also possible to provide a ``colormap`` to :meth:`.PlotWidget.addImage` to override this default for an image: .. code-block:: python colormap = {'name': 'magma', 'normalization': 'log', 'autoscale': False, 'vmin': 1.2, 'vmax': 1.8} data = numpy.random.random(512 * 512).reshape(512, -1) + 1. plot.addImage(data, colormap=colormap) As for `Origin and scale`_, when updating an image, if ``colormap`` is not provided, the previous colormap will be used: .. code-block:: python data = numpy.random.random(512 * 512).reshape(512, -1) + 1. plot.addImage(data) # Keep previous colormap The colormap can be changed by the user from the widget's toolbar. Multiple images +++++++++++++++ In order to display multiple images at the same time, you need to provide a different ``legend`` string for each of them and to set the ``replace`` argument to ``False``: .. code-block:: python data = numpy.random.random(512 * 512).reshape(512, -1) plot.addImage(data, legend='random', replace=False) data = numpy.arange(512 * 512.).reshape(512, -1) plot.addImage(data, legend='arange', replace=False, origin=(512, 512)) To update an image, call :meth:`.PlotWidget.addImage` with the ``legend`` of the curve you want to udpdate. By default, the new image will keep the same colormap, origin and scale as the image it is updating: .. code-block:: python data = (512 * 512. - numpy.arange(512 * 512.)).reshape(512, -1) plot.addImage(data, legend='arange', replace=False) # Beware of replace=False To remove an image from the plot, call :meth:`.PlotWidget.remove` with the ``legend`` of the image you want to remove: .. code-block:: python plot.remove('random') Control plot axes ----------------- The following examples illustrate the API to control the plot axes. Labels and title ++++++++++++++++ Use :meth:`.PlotWidget.setGraphTitle` to set the plot main title. Use :meth:`.PlotWidget.setGraphXLabel` and :meth:`.PlotWidget.setGraphYLabel` to set the axes text labels: .. code-block:: python plot.setGraphTitle('My plot') plot.setGraphXLabel('X') plot.setGraphYLabel('Y') Axes limits +++++++++++ Different methods allows to get and set the data limits displayed on each axis. The following code moves the visible plot area to the right: .. code-block:: python xmin, xmax = plot.getGraphXLimits() offset = 0.1 * (xmax - xmin) plot.setGraphXLimits(xmin + offset, xmax + offset) :meth:`.PlotWidget.resetZoom` set the plot limits to the bounds of the data: .. code-block:: python plot.resetZoom() See :meth:`.PlotWidget.resetZoom`, :meth:`.PlotWidget.setLimits`, :meth:`.PlotWidget.getGraphXLimits`, :meth:`.PlotWidget.setGraphXLimits`, :meth:`.PlotWidget.getGraphYLimits`, :meth:`.PlotWidget.setGraphYLimits` for details. Axes ++++ Different methods allow plot axes modifications: .. code-block:: python plot.setYAxisInverted(True) # Makes the Y axis pointing downward plot.setKeepDataAspectRatio(True) # To keep aspect ratio between X and Y axes See :meth:`.PlotWidget.setYAxisInverted`, :meth:`.PlotWidget.setKeepDataAspectRatio` for details. .. code-block:: python plot.setGraphGrid(which='both') # To show a grid for both minor and major axes ticks # Use logarithmic axes plot.setXAxisLogarithmic(True) plot.setYAxisLogarithmic(True) See :meth:`.PlotWidget.setGraphGrid`, :meth:`.PlotWidget.setXAxisLogarithmic`, :meth:`.PlotWidget.setYAxisLogarithmic` for details.