Skip to main content
`Ctrl`+`K`

# `silx.sx`: Using silx from Python Interpreter

This is a convenient package to use from Python or IPython interpreter. It loads the main features of silx and provides high-level functions.

    >>> from silx import sx

When used in an interpreter is sets-up Qt and loads some silx widgets. In a jupyter / IPython notebook, to set-up Qt and loads silx widgets, you must then call:

    >>> sx.enable_gui()

When used in IPython, it also runs `%pylab`, thus importing numpy and matplotlib.

## Plot functions

The following functions plot curves and images with silx widgets:

- `plot()` for curves

- `imshow()` for images

- `scatter()` for scatter plot

The `ginput()` function handles user selection on those widgets.

Note

Those functions are not available from a notebook.

### `plot()`

plot(*args, **kwargs)

  Plot curves in a `Plot1D` widget.

  How to use:

      >>> 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.')

  Supported symbols:

  > - ‘o’ circle

  > - ‘.’ point

  > - ‘,’ pixel

  > - ‘+’ cross

  > - ‘x’ x-cross

  > - ‘d’ diamond

  > - ‘s’ square

  Supported types of line:

  > - ‘ ‘ no line

  > - ‘-’ solid line

  > - ‘–’ dashed line

  > - ‘-.’ dash-dot line

  > - ‘:’ dotted line

  If provided, the names arguments color, linestyle, linewidth and marker override any style provided to a curve.

  This function supports a subset of matplotlib.pyplot.plot arguments.

  Parameters:

    - color (str) – Color to use for all curves (default: None)

    - linestyle (str) – Type of line to use for all curves (default: None)

    - linewidth (float) – With of all the curves (default: 1)

    - marker (str) – Symbol to use for all the curves (default: None)

    - title (str) – The title of the Plot widget (default: None)

    - xlabel (str) – The label of the X axis (default: None)

    - ylabel (str) – The label of the Y axis (default: None)

  Returns:

    The widget plotting the curve(s)

  Return type:

    silx.gui.plot.Plot1D

### `imshow()`

imshow(data=None, cmap=None, norm='linear', vmin=None, vmax=None, aspect=False, origin='upper', scale=(1.0, 1.0), title='', xlabel='X', ylabel='Y')

  Plot an image in a `Plot2D` widget.

  How to use:

      >>> from silx import sx
      >>> import numpy

      >>> data = numpy.random.random(1024 * 1024).reshape(1024, 1024)
      >>> plt = sx.imshow(data, title='Random data')

  By default, the image origin is displayed in the upper left corner of the plot. To invert the Y axis, and place the image origin in the lower left corner of the plot, use the origin parameter:

      >>> plt = sx.imshow(data, origin='lower')

  This function supports a subset of matplotlib.pyplot.imshow arguments.

  Parameters:

    - data (numpy.ndarray-like with 2 dimensions) – data to plot as an image

    - cmap (str) – The name of the colormap to use for the plot. It also supports a numpy array containing a RGB LUT, or a colors.Colormap instance.

    - norm (str) – The normalization of the colormap: ‘linear’ (default) or ‘log’

    - vmin (float) – The value to use for the min of the colormap

    - vmax (float) – The value to use for the max of the colormap

    - aspect (bool) – True to keep aspect ratio (Default: False)

    - origin (str or 2-tuple of floats) – Either image origin as the Y axis orientation: ‘upper’ (default) or ‘lower’ or the coordinates (ox, oy) of the image origin in the plot.

    - scale (2-tuple of floats) – (sx, sy) The scale of the image in the plot (i.e., the size of the image’s pixel in plot coordinates)

    - title (str) – The title of the Plot widget

    - xlabel (str) – The label of the X axis

    - ylabel (str) – The label of the Y axis

  Returns:

    The widget plotting the image

  Return type:

    silx.gui.plot.Plot2D

### `scatter()`

scatter(x=None, y=None, value=None, size=None, marker=None, cmap=None, norm='linear', vmin=None, vmax=None)

  Plot scattered data in a `ScatterView` widget.

  How to use:

      >>> from silx import sx
      >>> import numpy

      >>> x = numpy.random.random(100)
      >>> y = numpy.random.random(100)
      >>> values = numpy.random.random(100)
      >>> plt = sx.scatter(x, y, values, cmap='viridis')

  > Supported symbols:

  > - ‘o’ circle

  > - ‘.’ point

  > - ‘,’ pixel

  > - ‘+’ cross

  > - ‘x’ x-cross

  > - ‘d’ diamond

  > - ‘s’ square

  This function supports a subset of matplotlib.pyplot.scatter arguments.

  Parameters:

    - x (numpy.ndarray) – 1D array-like of x coordinates

    - y (numpy.ndarray) – 1D array-like of y coordinates

    - value (numpy.ndarray) – 1D array-like of data values

    - size (float) – Size^2 of the markers

    - marker (str) – Symbol used to represent the points

    - cmap (str) – The name of the colormap to use for the plot

    - norm (str) – The normalization of the colormap: ‘linear’ (default) or ‘log’

    - vmin (float) – The value to use for the min of the colormap

    - vmax (float) – The value to use for the max of the colormap

  Returns:

    The widget plotting the scatter plot

  Return type:

    silx.gui.plot.ScatterView.ScatterView

### `ginput()`

ginput(n=1, timeout=30, plot=None)

  Get input points on a plot.

  If no plot is provided, it uses a plot widget created with either `silx.sx.plot()` or `silx.sx.imshow()`.

  How to use:

      >>> from silx import sx

      >>> sx.imshow(image)  # Plot the image
      >>> sx.ginput(1)  # Request selection on the image plot
      ((0.598, 1.234))

  How to get more information about the selected positions:

      >>> positions = sx.ginput(1)

      >>> positions[0].getData()  # Returns value(s) at selected position

      >>> positions[0].getIndices()  # Returns data indices at selected position

      >>> positions[0].getItem()  # Returns plot item at selected position

  Parameters:

    - n (int) – Number of points the user need to select

    - timeout (float) – Timeout in seconds before ginput returns event if selection is not completed

    - plot (silx.gui.plot.PlotWidget.PlotWidget) – An optional PlotWidget from which to get input

  Returns:

    List of clicked points coordinates (x, y) in plot

  Raises:

    ValueError – If provided plot is not a PlotWidget

## 3D plot functions

The following functions plot 3D data with silx widgets (it requires OpenGL):

- `contour3d()` for isosurfaces (and cut plane) in a 3D scalar field

- `points3d()` for 2D/3D scatter plots

Note

Those functions are not available from a notebook.

### `contour3d()`

contour3d(scalars, contours=1, copy=True, color=None, colormap='viridis', vmin=None, vmax=None, opacity=1.0)

  Plot isosurfaces of a 3D scalar field in a `ScalarFieldView` widget.

  How to use:

      >>> from silx import sx

  Provided data, a 3D scalar field as a numpy array of float32:

      >>> plot3d_window = sx.contour3d(data)

  Alternatively you can provide the level of the isosurfaces:

      >>> plot3d_window = sx.contour3d(data, contours=[0.2, 0.4])

  This function provides a subset of mayavi.mlab.contour3d arguments.

  Parameters:

    - scalars (numpy.ndarray of float32 with 3 dimensions) – The 3D scalar field to visualize

    - contours (Union[int, float, List[float]]) – Either the number of isosurfaces to draw (as an int) or the isosurface level (as a float) or a list of isosurface levels (as a list of float)

    - copy (bool) – True (default) to make a copy of scalars. False to avoid this copy (do not modify provided data afterwards)

    - color – Color.s to use for isosurfaces. Either a single color or a list of colors (one for each isosurface). A color can be defined by its name (as a str) or as RGB(A) as float or uint8.

    - colormap (str) – If color is not provided, this colormap is used for coloring isosurfaces.

    - vmin (Union[float, None]) – Minimum value of the colormap

    - vmax (Union[float, None]) – Maximum value of the colormap

    - opacity (float) – Transparency of the isosurfaces as a float in [0., 1.]

  Returns:

    The widget used to visualize the data

  Return type:

    ScalarFieldView

### `points3d()`

points3d(x, y, z=None, values=0.0, copy=True, colormap='viridis', vmin=None, vmax=None, mode=None)

  Plot a 3D scatter plot in a `SceneWindow` widget.

  How to use:

      >>> from silx import sx

  Provided x, y, z, values, 4 numpy array of float32:

      >>> plot3d_window = sx.points3d(x, y, z)

      >>> plot3d_window = sx.points3d(x, y, z, values)

  This function provides a subset of mayavi.mlab.points3d arguments.

  Parameters:

    - x (numpy.ndarray) – X coordinates of the points

    - y (numpy.ndarray) – Y coordinates of the points

    - z (numpy.ndarray) – Z coordinates of the points (optional)

    - values (numpy.ndarray) – Values at each point (optional)

    - copy (bool) – True (default) to make a copy of scalars. False to avoid this copy (do not modify provided data afterwards)

    - colormap (str) – Colormap to use for coding points as colors.

    - vmin (Union[float, None]) – Minimum value of the colormap

    - vmax (Union[float, None]) – Maximum value of the colormap

    - mode (str) –

      The type of marker to use

      - Circle: ‘o’, ‘2dcircle’

      - Diamond: ‘d’, ‘2ddiamond’

      - Square: ‘s’, ‘2dsquare’

      - Plus: ‘+’

      - Cross: ‘x’, ‘2dcross’

      - Star: ‘*’

      - Vertical line: ‘|’

      - Horizontal line: ‘_’, ‘2ddash’

      - Point: ‘.’

      - Pixel: ‘,’

  Returns:

    The widget used to visualize the data

  Return type:

    SceneWindow

## Widgets

The widgets of the `silx.gui.plot` package are also exposed in this package. See `silx.gui.plot` for documentation.

## Input/Output

The content of the `silx.io` package is also exposed in this package. See `silx.io` for documentation.

## Math

The following classes from `silx.math` are exposed in this package:

- `Histogramnd`

- `HistogramndLut`

- `leastsq`