matplotlib package

Introduction

MicroPython, the programming language for the ALPACA, does not natively support plotting, as it is intended to interface over a text-based serial interface. For NB2214 however, it is convenient to be able to visualize the signals that have been acquired. As the ALPACA is used together with Jupyter, the plots be shown here.

To make this possible, nb2214-micropython has to work together with a specialized kernel for Jupyter, called the ALPACA kernel. With both pieces of software installed, a subset of the widely-used matplotlib module is available for use.

Specifically, plotting can (only) be done using the matplotlib.pyplot module. This is the familiar state-based interface to matplotlib, which provides a MATLAB-like way of plotting. Figures are then automatically shown in the cell in Jupyter.

Note that this means that a lot of the extended functionality of matplotlib is unavailable, like subplots. A list of available functions and their usage, which is similar or identical to that of “normal” matplotlib can be found on this page.

This module does, however, implement a function not seen in the matplotlib: matplotlib.pyplot.liveplot(), which means to do live plotting during a measurement.

Submodules

matplotlib.pyplot module

matplotlib.pyplot Module

The matplotlib.pyplot module provides a MATLAB-like plotting framework within MicroPython on the ALPACA. It allows you to create static and live visualizations in a convenient manner.

Usage:

To use matplotlib.pyplot, import it using:

>>> import matplotlib.pyplot as plt

This import convention allows you to access the functions within the module using the alias plt.

Examples

Create a simple plot using points with x and y values.

>>> import matplotlib.pyplot as plt
>>>
>>> x = [1, 2, 3, 4, 5]
>>> y = [2, 4, 6, 8, 10]
>>> plt.plot(x, y) # Create a plot
>>>
>>> # Customize the plot
>>> plt.xlabel('X-axis')
>>> plt.ylabel('Y-axis')
>>> plt.title('Simple Plot')

Key Functions::

matplotlib.pyplot.plot(): Create a line or scatter plot.
matplotlib.pyplot.xlabel(): Set the label for the x-axis.
matplotlib.pyplot.ylabel(): Set the label for the y-axis.
matplotlib.pyplot.title(): Set the title of the plot.
matplotlib.pyplot.legend(): Add a legend to the plot.

matplotlib.pyplot.axhline(y=0, xmin=0, xmax=1, **kwargs) → None

Adds a horizontal line across the axis.

Parameters:

y (float, optional) – y position in data coordinates of the horizontal line. Default is 0.
xmin (float, optional) – Should be between 0 and 1, 0 being the far left of the plot, 1 the far right. Default is 0.
xmax (float, optional) – Should be between 0 and 1, 0 being the far left of the plot, 1 the far right. Default is 1.
**kwargs – Valid keyword arguments are .Line2D properties, excluding ‘transform’.

Returns:

None

See also

matplotlib.pyplot.vlines() : Add vertical lines in data coordinates.

Examples

Draw a thick red vline at x = 0 that spans the yrange:
>>> axvline(linewidth=4, color='r')
Draw a default vline at x = 1 that spans the yrange:
>>> axvline(x=1)
Draw a default vline at x = .5 that spans the middle half of the yrange:
>>> axvline(x=.5, ymin=0.25, ymax=0.75)

matplotlib.pyplot.grid(*args, **kwargs) → None

Display grid lines on the current axes.

Parameters:

b (bool, optional) – Whether to show the grid lines. Default is True.
which (str or list of str, optional) – The grid lines to apply the changes. Options are: - ‘major’ : Show major grid lines. - ‘minor’ : Show minor grid lines. - ‘both’ : Show both major and minor grid lines. Default is ‘major’.
axis (str or None, optional) – The axis on which to turn the grid lines. Options are: - ‘both’ : Apply changes to both x and y axes. - ‘x’ : Apply changes to the x-axis only. - ‘y’ : Apply changes to the y-axis only. - None : Equivalent to ‘both’. Default is ‘both’.
**kwargs – Additional keyword arguments controlling the appearance of the grid lines. See the matplotlib.pyplot.grid documentation for available options.

Returns:

None

matplotlib.pyplot.hlines(y, xmin, xmax, colors=None, linestyles='solid', label='', data=None, **kwargs) → None

Add horizontal lines to the current axes.

Parameters:

y (float or list of float) – y positions in data coordinates of the horizontal lines.
xmin (float) – Should be between 0 and 1, 0 being the far left of the plot, 1 the far right.
xmax (float) – Should be between 0 and 1, 0 being the far left of the plot, 1 the far right.
colors (str or list of str, optional) – Color or list of colors for the lines. Default is None.
linestyles (str or list of str, optional) – Line style or list of line styles. Default is ‘solid’.
label (str, optional) – Label for the lines. Default is an empty string.
**kwargs – Additional keyword arguments controlling the appearance of the lines. See the matplotlib.pyplot.hlines documentation for available options.

Returns:

None

matplotlib.pyplot.legend(*args, **kwargs) → None

Place a legend on the current axes.

Parameters:

*args – Variable-length argument list of legend entries. Each entry can be a string or a ~matplotlib.lines.Line2D.
loc (str or tuple, optional) – The location of the legend. Options are: - ‘best’ : Automatically choose the optimal location. - ‘upper right’, ‘upper left’, ‘lower left’, ‘lower right’ : Place at the corresponding corner. - ‘right’ : Place at the right of the plot. - ‘center left’, ‘center right’ : Place at the center of the left or right side. - ‘lower center’, ‘upper center’ : Place at the center of the bottom or top side. - ‘center’ : Place at the center of the plot. - (float, float) : Place at the specified coordinates. Default is ‘best’.
shadow (bool, optional) – Whether to draw a shadow behind the legend. Default is False.
fontsize (int or str, optional) – The font size of the legend. If not specified, defaults to the global font size.
frameon (bool, optional) – Whether to draw a frame around the legend. Default is True.
fancybox (bool, optional) – Whether to use a rounded box for the legend. Default is True.
framealpha (float, optional) – The alpha transparency of the legend frame. Default is 1.0 (fully opaque).
edgecolor (str, optional) – The color of the legend frame border. If not specified, uses the Axes’ edge color.
bbox_to_anchor (tuple, optional) – The bbox that the legend will be anchored. Only takes effect if loc is a string. Default is None.
**kwargs – Additional keyword arguments controlling the appearance of the legend. See the matplotlib.pyplot.legend documentation for available options.

Returns:

None

matplotlib.pyplot.liveplot(*args, labels=None) → None

Plot live to Jupyter.

Live plotting can be done by adding the magic command:

%plot --mode live

to the top of the code in Jupyter. Incoming data is automatically stored and appended to older data. The x-axis of the plot is automatically labeled with the time elapsed from the start of the code to the arrival of the data in the serial output.

Parameters:

*args – An arbitrary amount of variables to plot.
labels (list, optional) – An optional list of labels, one for each variable to plot.

Returns:

None

Note

Due to differences in caching, the live plot flickers when Jupyter is run in the Firefox browser. In this case, it is best to use the Edge browser instead.

Examples

Using functiongenerator.FuncGen a sine wave is created, measured using the analog input pins of the ALPACA, and plotted live. Note the use of a label:

>>> %plot --mode live
>>>
>>> import time
>>> from machine import ADC, Pin
>>> import matplotlib.pyplot as plt
>>> from functiongenerator import FuncGen, Sine
>>>
>>> adc = ADC(Pin(26))
>>>
>>> with FuncGen(Sine(Vpp=2, offset=0, freq=1)):
        for _ in range(250):
            value = adc.read_u16() * 5.0354e-05 # Convert to volts
            plt.liveplot(value, labels=('voltage', ))

Two values can also be plotted simulataneously:

>>> %plot --mode live
>>>
>>> adc_1 = ADC(Pin(26))
>>> adc_2 = ADC(Pin(27))
>>>
>>> with FuncGen(Sine(Vpp=2, offset=0, freq=1)):
    for _ in range(250):
        value_1 = adc_1.read_u16() * 5.0354e-05
        value_2 = adc_2.read_u16() * 5.0354e-05
        plt.liveplot(value_1, value_2)

Two values can also be plotted simulataneously with labels:

>>> %plot --mode live
>>>
>>> with FuncGen(Sine(Vpp=2, offset=0, freq=1)):
    for _ in range(250):
        value_1 = adc_1.read_u16() * 5.0354e-05
        value_2 = adc_2.read_u16() * 5.0354e-05
        plt.liveplot(value_1, value_2, labels=('Vin', 'Vout'))

matplotlib.pyplot.plot(*args, scalex=True, scaley=True, data=None, **kwargs) → None

Plot y versus x as lines and/or markers.

Call signatures:

plot(y) # plot y using x as index array 0..N-1
plot(y, ‘o’) # plot y using x as index array 0..N-1 and marker ‘o’
plot(x, y) # plot x and y using default line style and color
plot(x, y, ‘bo’) # plot x and y using blue circle markers
plot(x, y, ‘b-’) # plot x and y using blue solid line
plot(y, ‘r+’, x, ‘g-’) # plot y using red plus markers and x using green solid line

Parameters:

*args – Variable-length argument list. - x (array-like or None): The x-coordinates of the data points. If None, the index of y is used. - y (array-like): The y-coordinates of the data points. - fmt (str, optional): A format string that controls the appearance of the lines and markers. Default is an empty string.
scalex (bool, optional) – Whether to scale the x-axis. Default is True.
scaley (bool, optional) – Whether to scale the y-axis. Default is True.
**kwargs – Additional keyword arguments controlling the appearance of the lines and markers. See the matplotlib.pyplot.plot documentation for available options.

Returns:

None

Note

The fmt string can be used to specify line styles, markers, and colors in a concise way.

matplotlib.pyplot.title(label, fontdict=None, loc=None, pad=None, *, y=None, **kwargs) → None

Set the title of the current axes.

Parameters:

label (str) – The title text.
fontdict (dict, optional) – A dictionary containing font properties for the title. Default is None.
loc (str, optional) – The location of the title. Options are: - ‘center’ : Centered title. - ‘left’ : Left-aligned title. - ‘right’ : Right-aligned title. Default is None, which implies center.
pad (float, optional) – The offset of the title from the top of the axes. Default is None.
y (float, optional) – The y position of the title. Default is None.
**kwargs – Additional keyword arguments controlling the appearance of the title. See the matplotlib.pyplot.title documentation for available options.

Returns:

None

matplotlib.pyplot.vlines(x, ymin, ymax, colors=None, linestyles='solid', label='', *, data=None, **kwargs) → None

Add vertical lines to the current axes.

Parameters:

x (float or list of float) – x positions in data coordinates of the vertical lines.
ymin (float) – Should be between 0 and 1, 0 being the bottom of the plot, 1 the top.
ymax (float) – Should be between 0 and 1, 0 being the bottom of the plot, 1 the top.
colors (str or list of str, optional) – Color or list of colors for the lines. Default is None.
linestyles (str or list of str, optional) – Line style or list of line styles. Default is ‘solid’.
label (str, optional) – Label for the lines. Default is an empty string.
**kwargs – Additional keyword arguments controlling the appearance of the lines. See the matplotlib.pyplot.vlines documentation for available options.

Returns:

None

matplotlib.pyplot.xlabel(xlabel, fontdict=None, labelpad=None, *, loc=None, **kwargs) → None

Set the label for the x-axis.

Parameters:

xlabel (str) – The label text for the x-axis.
fontdict (dict, optional) – A dictionary containing font properties for the label. Default is None.
labelpad (float, optional) – The offset of the label from the x-axis. Default is None.
loc (str, optional) – The location of the label. Options are: - ‘center’ : Centered label. - ‘left’ : Left-aligned label. - ‘right’ : Right-aligned label. Default is None, which implies center.
**kwargs – Additional keyword arguments controlling the appearance of the x-axis label. See the matplotlib.pyplot.xlabel documentation for available options.

Returns:

None

matplotlib.pyplot.xlim(*args, **kwargs) → None

Set the x limits of the current axes.

Parameters:

left (float, optional) – The left limit of the x-axis. Default is None.
right (float, optional) – The right limit of the x-axis. Default is None.

Returns:

None

Examples

Set x-axis limits to [0, 10]:
```
>>> xlim(0, 10)
```
Adjust the right limit, leaving the left limit unchanged:
```
>>> xlim(right=5)
```

matplotlib.pyplot.xscale(value, **kwargs) → None

Set the scale of the x-axis.

Parameters:

value (str) – The scale type for the x-axis. Available options: - ‘linear’ : Linear scale. - ‘log’ : Logarithmic scale. - ‘symlog’ : Symmetrical log scale. - ‘logit’ : Logit scale.
**kwargs – Additional keyword arguments controlling the scale of the x-axis.

Returns:

None

matplotlib.pyplot.xticks(ticks=None, labels=None, **kwargs) → None

Set the current tick locations and labels of the x-axis.

Parameters:

ticks (array-like, optional) – The list of xtick locations. Passing an empty list removes all xticks.
labels (array-like, optional) – The labels to place at the given ticks locations. This argument can only be passed if ticks is passed as well.
**kwargs – .Text properties can be used to control the appearance of the labels.

Returns:

None

matplotlib.pyplot.ylabel(ylabel, fontdict=None, labelpad=None, *, loc=None, **kwargs) → None

Set the label for the y-axis.

Parameters:

ylabel (str) – The label text for the y-axis.
fontdict (dict, optional) – A dictionary containing font properties for the label. Default is None.
labelpad (float, optional) – The offset of the label from the y-axis. Default is None.
loc (str, optional) – The location of the label. Options are: - ‘center’ : Centered label. - ‘left’ : Left-aligned label. - ‘right’ : Right-aligned label. Default is None, which implies center.
**kwargs – Additional keyword arguments controlling the appearance of the y-axis label. See the matplotlib.pyplot.ylabel documentation for available options.

Returns:

None

matplotlib.pyplot.ylim(*args, **kwargs) → None

Set the y-limits of the current axes.

Setting limits turns autoscaling off for the y-axis.

Parameters:

bottom (float, optional) – The bottom limit of the y-axis. Default is None.
top (float, optional) – The top limit of the y-axis. Default is None.

Returns:

None

Examples

Set y-axis limits to [-5, 5]:
```
>>> ylim(-5, 5)
```
Adjust the top limit, leaving the bottom limit unchanged:
```
>>> ylim(top=2)
```

matplotlib.pyplot.yscale(value, **kwargs) → None

Set the scale of the y-axis.

Parameters:

value (str) – The scale type for the y-axis. Available options: - ‘linear’ : Linear scale. - ‘log’ : Logarithmic scale. - ‘symlog’ : Symmetrical log scale. - ‘logit’ : Logit scale.
**kwargs – Additional keyword arguments controlling the scale of the y-axis.

Returns:

None

matplotlib.pyplot.yticks(ticks=None, labels=None, **kwargs) → None

Set the current tick locations and labels of the y-axis.

Parameters:

ticks (array-like, optional) – The list of ytick locations. Passing an empty list removes all yticks.
labels (array-like, optional) – The labels to place at the given ticks locations. This argument can only be passed if ticks is passed as well.
**kwargs – .Text properties can be used to control the appearance of the labels.

Returns:

None

matplotlib package

Introduction

Submodules

matplotlib.pyplot module

Module contents