Plotting utilities

Easy-to-use plotting utilities based on Bokeh.

arlpy.plot.box(left=None, right=None, top=None, bottom=None, color='yellow', alpha=0.1, hold=False)

Add a highlight box to a plot.

Parameters:
  • left – x location of left of box
  • right – x location of right of box
  • top – y location of top of box
  • bottom – y location of bottom of box
  • color – text color (see Bokeh colors)
  • alpha – transparency (0-1)
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.box(left=5, right=10, top=8)
arlpy.plot.color(n)

Get a numbered color to cycle over a set of colors.

>>> import arlpy.plot
>>> arlpy.plot.color(0)
'blue'
>>> arlpy.plot.color(1)
'red'
>>> arlpy.plot.plot([0, 20], [0, 10], color=arlpy.plot.color(3))
arlpy.plot.enable_javascript(b)

Enable/disable Javascript.

Parameters:b – True to use Javacript, False to avoid use of Javascript

Jupyterlab does not support Javascript output. To avoid error messages, Javascript can be disabled using this call. This removes an optimization to replace non-interactive plots with static images, but other than that does not affect functionality.

arlpy.plot.figsize(x, y)

Set the default figure size in pixels.

Parameters:
  • x – figure width
  • y – figure height
class arlpy.plot.figure(title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xtype='auto', ytype='auto', width=None, height=None, interactive=None)

Create a new figure, and optionally automatically display it.

Parameters:
  • title – figure title
  • xlabel – x-axis label
  • ylabel – y-axis label
  • xlim – x-axis limits (min, max)
  • ylim – y-axis limits (min, max)
  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)
  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)
  • width – figure width in pixels
  • height – figure height in pixels
  • interactive – enable interactive tools (pan, zoom, etc) for plot

This function can be used in standalone mode to create a figure:

>>> import arlpy.plot
>>> arlpy.plot.figure(title='Demo 1', width=500)
>>> arlpy.plot.plot([0,10], [0,10])

Or it can be used as a context manager to create, hold and display a figure:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 2', width=500):
>>>     arlpy.plot.plot([0,10], [0,10], color='blue', legend='A')
>>>     arlpy.plot.plot([10,0], [0,10], marker='o', color='green', legend='B')

It can even be used as a context manager to work with Bokeh functions directly:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 3', width=500) as f:
>>>     f.line([0,10], [0,10], line_color='blue')
>>>     f.square([3,7], [4,5], line_color='green', fill_color='yellow', size=10)
arlpy.plot.freqz(b, a=1, fs=2.0, worN=None, whole=False, degrees=True, style='solid', thickness=1, title=None, xlabel='Frequency (Hz)', xlim=None, ylim=None, width=None, height=None, hold=False, interactive=None)

Plot frequency response of a filter.

This is a convenience function to plot frequency response, and internally uses scipy.signal.freqz() to estimate the response. For further details, see the documentation for scipy.signal.freqz().

Parameters:
  • b – numerator of a linear filter
  • a – denominator of a linear filter
  • fs – sampling rate in Hz (optional, normalized frequency if not specified)
  • worN – see scipy.signal.freqz()
  • whole – see scipy.signal.freqz()
  • degrees – True to display phase in degrees, False for radians
  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)
  • thickness – line width in pixels
  • title – figure title
  • xlabel – x-axis label
  • ylabel1 – y-axis label for magnitude
  • ylabel2 – y-axis label for phase
  • xlim – x-axis limits (min, max)
  • ylim – y-axis limits (min, max)
  • width – figure width in pixels
  • height – figure height in pixels
  • interactive – enable interactive tools (pan, zoom, etc) for plot
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy
>>> arlpy.plot.freqz([1,1,1,1,1], fs=120000);
arlpy.plot.gcf()

Get the current figure.

Returns:handle to the current figure
arlpy.plot.hlines(y, color='gray', style='dashed', thickness=1, hold=False)

Draw horizontal lines on a plot.

Parameters:
  • y – y location of lines
  • color – line color (see Bokeh colors)
  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)
  • thickness – line width in pixels
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.hlines(3, color='red', style='dotted')
arlpy.plot.hold(enable=True)

Combine multiple plots into one.

Parameters:enable – True to hold plot, False to release hold
Returns:old state of hold if enable is True 
>>> import arlpy.plot
>>> oh = arlpy.plot.hold()
>>> arlpy.plot.plot([0,10], [0,10], color='blue', legend='A')
>>> arlpy.plot.plot([10,0], [0,10], marker='o', color='green', legend='B')
>>> arlpy.plot.hold(oh)
arlpy.plot.image(img, x=None, y=None, colormap='Plasma256', clim=None, clabel=None, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xtype='auto', ytype='auto', width=None, height=None, hold=False, interactive=None)

Plot a heatmap of 2D scalar data.

Parameters:
  • img – 2D image data
  • x – x-axis range for image data (min, max)
  • y – y-axis range for image data (min, max)
  • colormap – named color palette or Bokeh ColorMapper (see Bokeh palettes)
  • clim – color axis limits (min, max)
  • clabel – color axis label
  • title – figure title
  • xlabel – x-axis label
  • ylabel – y-axis label
  • xlim – x-axis limits (min, max)
  • ylim – y-axis limits (min, max)
  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)
  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)
  • width – figure width in pixels
  • height – figure height in pixels
  • interactive – enable interactive tools (pan, zoom, etc) for plot
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.image(np.random.normal(size=(100,100)), colormap='Inferno256')
arlpy.plot.interactive(b)

Set default interactivity for plots.

Parameters:b – True to enable interactivity, False to disable it
arlpy.plot.iqplot(data, marker='.', color=None, labels=None, filled=False, size=None, title=None, xlabel=None, ylabel=None, xlim=[-2, 2], ylim=[-2, 2], width=None, height=None, hold=False, interactive=None)

Plot signal points.

Parameters:
  • data – complex baseband signal points
  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)
  • color – marker/text color (see Bokeh colors)
  • labels – label for each signal point, or True to auto-generate labels
  • filled – filled markers or outlined ones
  • size – marker/text size (e.g. 5, ‘8pt’)
  • title – figure title
  • xlabel – x-axis label
  • ylabel – y-axis label
  • xlim – x-axis limits (min, max)
  • ylim – y-axis limits (min, max)
  • width – figure width in pixels
  • height – figure height in pixels
  • interactive – enable interactive tools (pan, zoom, etc) for plot
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy
>>> import arlpy.plot
>>> arlpy.plot.iqplot(arlpy.comms.psk(8))
>>> arlpy.plot.iqplot(arlpy.comms.qam(16), color='red', marker='x')
>>> arlpy.plot.iqplot(arlpy.comms.psk(4), labels=['00', '01', '11', '10'])
class arlpy.plot.many_figures(figsize=None)

Create a grid of many figures.

Parameters:figsize – default size of figure in grid as (width, height) 
>>> import arlpy.plot
>>> with arlpy.plot.many_figures(figsize=(300,200)):
>>>     arlpy.plot.plot([0,10], [0,10])
>>>     arlpy.plot.plot([0,10], [0,10])
>>>     arlpy.plot.next_row()
>>>     arlpy.plot.next_column()
>>>     arlpy.plot.plot([0,10], [0,10])
arlpy.plot.next_column()

Move to the next column in a grid of many figures.

arlpy.plot.next_row()

Move to the next row in a grid of many figures.

arlpy.plot.plot(x, y=None, fs=None, maxpts=10000, pooling=None, color=None, style='solid', thickness=1, marker=None, filled=False, size=6, mskip=0, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xtype='auto', ytype='auto', width=None, height=None, legend=None, hold=False, interactive=None)

Plot a line graph or time series.

Parameters:
  • x – x data or time series data (if y is None)
  • y – y data or None (if time series)
  • fs – sampling rate for time series data
  • maxpts – maximum number of points to plot (downsampled if more points provided)
  • pooling – pooling for downsampling (None, ‘max’, ‘min’, ‘mean’, ‘median’)
  • color – line color (see Bokeh colors)
  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’, None)
  • thickness – line width in pixels
  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)
  • filled – filled markers or outlined ones
  • size – marker size
  • mskip – number of points to skip marking (to avoid too many markers)
  • title – figure title
  • xlabel – x-axis label
  • ylabel – y-axis label
  • xlim – x-axis limits (min, max)
  • ylim – y-axis limits (min, max)
  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)
  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)
  • width – figure width in pixels
  • height – figure height in pixels
  • legend – legend text
  • interactive – enable interactive tools (pan, zoom, etc) for plot
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.plot([0,10], [1,-1], color='blue', marker='o', filled=True, legend='A', hold=True)
>>> arlpy.plot.plot(np.random.normal(size=1000), fs=100, color='green', legend='B')
arlpy.plot.psd(x, fs=2, nfft=512, noverlap=None, window='hann', color=None, style='solid', thickness=1, marker=None, filled=False, size=6, title=None, xlabel='Frequency (Hz)', ylabel='Power spectral density (dB/Hz)', xlim=None, ylim=None, width=None, height=None, legend=None, hold=False, interactive=None)

Plot power spectral density of a given time series signal.

Parameters:
  • x – time series signal
  • fs – sampling rate
  • nfft – segment size (see scipy.signal.welch)
  • noverlap – overlap size (see scipy.signal.welch)
  • window – window to use (see scipy.signal.welch)
  • color – line color (see Bokeh colors)
  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)
  • thickness – line width in pixels
  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)
  • filled – filled markers or outlined ones
  • size – marker size
  • title – figure title
  • xlabel – x-axis label
  • ylabel – y-axis label
  • xlim – x-axis limits (min, max)
  • ylim – y-axis limits (min, max)
  • width – figure width in pixels
  • height – figure height in pixels
  • legend – legend text
  • interactive – enable interactive tools (pan, zoom, etc) for plot
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.psd(np.random.normal(size=(10000)), fs=10000)
arlpy.plot.scatter(x, y, marker='.', filled=False, size=6, color=None, title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xtype='auto', ytype='auto', width=None, height=None, legend=None, hold=False, interactive=None)

Plot a scatter plot.

Parameters:
  • x – x data
  • y – y data
  • color – marker color (see Bokeh colors)
  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)
  • filled – filled markers or outlined ones
  • size – marker size
  • title – figure title
  • xlabel – x-axis label
  • ylabel – y-axis label
  • xlim – x-axis limits (min, max)
  • ylim – y-axis limits (min, max)
  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)
  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)
  • width – figure width in pixels
  • height – figure height in pixels
  • legend – legend text
  • interactive – enable interactive tools (pan, zoom, etc) for plot
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.scatter(np.random.normal(size=100), np.random.normal(size=100), color='blue', marker='o')
arlpy.plot.set_colors(c)

Provide a list of named colors to cycle over.

>>> import arlpy.plot
>>> arlpy.plot.set_colors(['red', 'blue', 'green', 'black'])
>>> arlpy.plot.color(2)
'green'
arlpy.plot.specgram(x, fs=2, nfft=None, noverlap=None, colormap='Plasma256', clim=None, clabel='dB', title=None, xlabel='Time (s)', ylabel='Frequency (Hz)', xlim=None, ylim=None, width=None, height=None, hold=False, interactive=None)

Plot spectrogram of a given time series signal.

Parameters:
  • x – time series signal
  • fs – sampling rate
  • nfft – FFT size (see scipy.signal.spectrogram)
  • noverlap – overlap size (see scipy.signal.spectrogram)
  • colormap – named color palette or Bokeh ColorMapper (see Bokeh palettes)
  • clim – color axis limits (min, max), or dynamic range with respect to maximum
  • clabel – color axis label
  • title – figure title
  • xlabel – x-axis label
  • ylabel – y-axis label
  • xlim – x-axis limits (min, max)
  • ylim – y-axis limits (min, max)
  • width – figure width in pixels
  • height – figure height in pixels
  • interactive – enable interactive tools (pan, zoom, etc) for plot
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.specgram(np.random.normal(size=(10000)), fs=10000, clim=30)
arlpy.plot.text(x, y, s, color='gray', size='8pt', hold=False)

Add text annotation to a plot.

Parameters:
  • x – x location of left of text
  • y – y location of bottom of text
  • s – text to add
  • color – text color (see Bokeh colors)
  • size – text size (e.g. ‘12pt’, ‘3em’)
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.text(7, 3, 'demo', color='orange')
arlpy.plot.theme(name)

Set color theme.

Parameters:name – name of theme 
>>> import arlpy.plot
>>> arlpy.plot.theme('dark')
arlpy.plot.use_static_images(b=True)

Use static images instead of dynamic HTML/Javascript in Jupyter notebook.

Parameters:b – True to use static images, False to use HTML/Javascript

Static images are useful when the notebook is to be exported as a markdown, LaTeX or PDF document, since dynamic HTML/Javascript is not rendered in these formats. When static images are used, all interactive functionality is disabled.

To use static images, you must have the following packages installed: selenium, pillow, phantomjs.

arlpy.plot.vlines(x, color='gray', style='dashed', thickness=1, hold=False)

Draw vertical lines on a plot.

Parameters:
  • x – x location of lines
  • color – line color (see Bokeh colors)
  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)
  • thickness – line width in pixels
  • hold – if set to True, output is not plotted immediately, but combined with the next plot
 
>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.vlines([7, 12])