trepr.plotting module

Plotting: Graphical representations of data extracted from datasets.

Graphical representations of TREPR data are an indispensable aspect of data analysis. To facilitate this, a series of different plotters are available. Additionally, savers (and stylers) are implemented.

Plotting relies on matplotlib, and mainly its object-oriented interface should be used for the actual plotting.

Generally, two types of plotters can be distinguished:

In the first case, the plot is usually handled using the plot() method of the respective trepr.dataset.Dataset object. Additionally, those plotters always only operate on the data of a single dataset, and the plot can easily be attached as a representation to the respective dataset. Plotters handling single datasets should always inherit from the aspecd.plotting.SinglePlotter class.

In the second case, the plot is handled using the plot() method of the aspecd.plotting.Plotter object, and the datasets are stored as a list within the plotter. As these plots span several datasets, there is no easy connection between a single dataset and such a plot in sense of representations stored in datasets. Plotters handling multiple datasets should always inherit from the aspecd.plotting.MultiPlotter class.

A note on array dimensions and axes

Something often quite confusing is the apparent inconsistency between the order of array dimensions and the order of axes. While we are used to assign axes in the order x, y, z, and assuming x to be horizontal, y vertical (and z sticking out of the paper plane), arrays are usually indexed row-first, column-second. That means, however, that if you simply plot a 2D array in axes, your first dimension is along the y axis, the second dimension along the x axis.

Therefore, as the axes of your datasets will always correspond to the array dimensions of your data, in case of 2D plots you will need to either use the information contained in the second axis object for your x axis label, and the information from the first axis object for your y axis label, or to transpose the data array.

Another aspect to have in mind is the position of the origin. Usually, in a Cartesian coordinate system, convention is to have the origin (0, 0) in the lower left of the axes (for the positive quadrant). However, for images, convention is to have the corresponding (0, 0) pixel located in the upper left edge of your image. Therefore, those plotting methods dealing with images will usually revert the direction of your y axis. Most probably, eventually you will have to check with real data and ensure the plotters to plot data and axes in a consistent fashion.

Types of concrete plotters

The trepr package comes with a series of concrete plotters included ready to be used, thanks to inheriting from the underlying ASpecD framework. As stated above, plotters can generally be divided into two types: plotters operating on single datasets and plotters combining the data of multiple datasets into a single figure.

Additionally, plotters can be categorised with regard to creating figures consisting of a single or multiple axes. The latter are plotters inheriting from the aspecd.plotting.CompositePlotter class. The latter can be thought of as templates for the other plotters to operate on, i.e. they provide the axes for other plotters to display their results.

Concrete plotters for single datasets

Concrete plotters for multiple datasets

Module documentation

class trepr.plotting.ScaledImagePlot

Bases: aspecd.plotting.SinglePlotter

Create a scaled image of a given dataset.

style

Defines whether the plot is done in xkcd style or not.

Type

str

description

Describes the aim of the class.

Type

str

Deprecated since version 0.1: Use SinglePlotter2D instead.

class trepr.plotting.LinePlot

Bases: aspecd.plotting.SinglePlotter

Create a 1D line plot of a given dataset.

style

Defines whether the plot is done in xkcd style or not.

Type

str

description

Describes the aim of the class.

Type

str

Deprecated since version 0.1: Use SinglePlotter1D instead.

class trepr.plotting.MultiLinePlot

Bases: aspecd.plotting.MultiPlotter

Plot multiple datasets as lines.

Deprecated since version 0.1: Use MultiPlotter1D instead.

class trepr.plotting.ColormapAdjuster(dataset=<trepr.dataset.ExperimentalDataset object>)

Bases: object

General facilities to adjust the colormap.

This class makes sure that the zero point of the colormap is equal to the zero point of the dataset.

Parameters

dataset (trepr.dataset.Dataset) – Dataset structure containing raw data as well as metadata.

dataset

Dataset to work with.

Type

trepr.dataset.Dataset

normalised_colormap

Colormap normalised to data of dataset.

Type

matplotlib.colormap

Deprecated since version 0.1: Will be included in aspecd.plotting.SinglePlotter2D.

adjust()

Perform all methods to adjust the colormap.

class trepr.plotting.SinglePlotter1D

Bases: aspecd.plotting.SinglePlotter1D

1D plots of single datasets.

Convenience class taking care of 1D plots of single datasets.

As the class is fully inherited from ASpecD for simple usage, see the ASpecD documentation of the aspecd.plotting.SinglePlotter1D class for details.

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    filename: output.pdf
class trepr.plotting.SinglePlotter2D

Bases: aspecd.plotting.SinglePlotter2D

2D plots of single datasets.

Convenience class taking care of 2D plots of single datasets.

As the class is fully inherited from ASpecD for simple usage, see the ASpecD documentation of the aspecd.plotting.SinglePlotter2D class for details.

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf

To change the axes (flip x and y axis):

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf
    parameters:
      switch_axes: True

To use another type (here: contour):

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf
    type: contour

To set the number of levels of a contour plot to 10:

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf
    type: contour
    parameters:
      levels: 10

To change the colormap (cmap) used:

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf
    properties:
      drawing:
        cmap: RdGy

Make sure to check the documentation of the ASpecD aspecd.plotting module for further parameters that can be set.

class trepr.plotting.MultiPlotter1D

Bases: aspecd.plotting.MultiPlotter1D

1D plots of multiple datasets.

Convenience class taking care of 1D plots of multiple datasets.

As the class is fully inherited from ASpecD for simple usage, see the ASpecD documentation of the aspecd.plotting.MultiPlotter1D class for details.

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    filename: output.pdf

To change the settings of each individual line (here the colour and label), supposing you have three lines, you need to specify the properties in a list for each of the drawings:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    filename: output.pdf
    properties:
      drawings:
        - color: '#FF0000'
          label: foo
        - color: '#00FF00'
          label: bar
        - color: '#0000FF'
          label: foobar

Important

If you set colours using the hexadecimal RGB triple prefixed by #, you need to explicitly tell YAML that these are strings, surrounding the values by quotation marks.

class trepr.plotting.MultiPlotter1DStacked

Bases: aspecd.plotting.MultiPlotter1DStacked

Stacked 1D plots of multiple datasets.

Convenience class taking care of 1D plots of multiple datasets.

As the class is fully inherited from ASpecD for simple usage, see the ASpecD documentation of the aspecd.plotting.MultiPlotter1DStacked class for details.

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: multiplot
  type: MultiPlotter1DStacked
  properties:
    filename: output.pdf

To change the settings of each individual line (here the colour and label), supposing you have three lines, you need to specify the properties in a list for each of the drawings:

- kind: multiplot
  type: MultiPlotter1DStacked
  properties:
    filename: output.pdf
    properties:
      drawings:
        - color: '#FF0000'
          label: foo
        - color: '#00FF00'
          label: bar
        - color: '#0000FF'
          label: foobar

Important

If you set colours using the hexadecimal RGB triple prefixed by #, you need to explicitly tell YAML that these are strings, surrounding the values by quotation marks.

Sometimes you want to have horizontal “zero lines” appear for each individual trace of the stacked plot. This can be achieved explicitly setting the “show_zero_lines” parameter to “True” that is set to “False” by default:

- kind: multiplot
  type: MultiPlotter1DStacked
  properties:
    filename: output.pdf
    parameters:
      show_zero_lines: True
class trepr.plotting.CompositePlotter

Bases: aspecd.plotting.CompositePlotter

Base class for plots consisting of multiple axes.

The underlying idea of composite plotters is to use a dedicated existing plotter for each axis and assign this plotter to the list of plotters of the CompositePlotter object. Thus the actual plotting task is left to the individual plotter and the CompositePlotter only takes care of the specifics of plots consisting of more than one axis.

As the class is fully inherited from ASpecD for simple usage, see the ASpecD documentation of the aspecd.plotting.CompositePlotter class for details.

class trepr.plotting.SingleCompositePlotter

Bases: aspecd.plotting.SingleCompositePlotter

Composite plotter for single datasets.

This composite plotter is used for different representations of one and the same dataset in multiple axes contained in one figure. In this respect, it works like all the other ordinary single plotters derived from SinglePlotter, i.e. it usually gets called by using the dataset’s aspecd.dataset.Dataset.plot() method.

As the class is fully inherited from ASpecD for simple usage, see the ASpecD documentation of the aspecd.plotting.SingleCompositePlotter class for details.

class trepr.plotting.Saver(filename=None)

Bases: aspecd.plotting.Saver

Base class for saving plots.

For basic saving of plots, no subclassing is necessary, as the save() method uses matplotlib.figure.Figure.savefig() and can cope with all possible parameters via the parameters property.

As the class is fully inherited from ASpecD for simple usage, see the ASpecD documentation of the aspecd.plotting.Saver class for details.