pyfar.plot¶

The following documents the pyfar plot functions. Refer to the concepts for more background information.

Functions:

`color`(color)	Return pyfar default color as HEX string.
`context`([style, after_reset])	Context manager for using plot styles temporarily.
`custom_subplots`(signal, plots[, ax, style])	Plot multiple pyfar plots with a custom layout and default parameters.
`freq`(signal[, dB, log_prefix, ...])	Plot the magnitude spectrum.
`freq_2d`(signal[, dB, log_prefix, ...])	2D color coded plot of magnitude spectra.
`freq_group_delay`(signal[, dB, log_prefix, ...])	Plot the magnitude and group delay spectrum (2 by 1 subplot).
`freq_group_delay_2d`(signal[, dB, ...])	2D color coded plot of magnitude spectra and group delay (2 by 1 subplot).
`freq_phase`(signal[, dB, log_prefix, ...])	Plot the magnitude and phase spectrum (2 by 1 subplot).
`freq_phase_2d`(signal[, dB, log_prefix, ...])	2D color coded plot of magnitude and phase spectra (2 by 1 subplot).
`group_delay`(signal[, unit, freq_scale, ax, ...])	Plot the group delay.
`group_delay_2d`(signal[, unit, freq_scale, ...])	2D color coded plot of the group delay.
`phase`(signal[, deg, unwrap, freq_scale, ax, ...])	Plot the phase of the spectrum.
`phase_2d`(signal[, deg, unwrap, freq_scale, ...])	2D color coded plot of phase spectra.
`plotstyle`([style])	Get the fullpath of the pyfar plotstyles `light` or `dark`.
`shortcuts`([show])	Show and return keyboard shortcuts for interactive figures.
`spectrogram`(signal[, dB, log_prefix, ...])	Plot blocks of the magnitude spectrum versus time.
`time`(signal[, dB, log_prefix, ...])	Plot the time signal.
`time_2d`(signal[, dB, log_prefix, ...])	2D color coded plot of time signals.
`time_freq`(signal[, dB_time, dB_freq, ...])	Plot the time signal and magnitude spectrum (2 by 1 subplot).
`time_freq_2d`(signal[, dB_time, dB_freq, ...])	2D color coded plot of time signals and magnitude spectra (2 by 1 subplot).
`use`([style])	Use plot style settings from a style specification.

pyfar.plot.color(color)[source]¶

Return pyfar default color as HEX string.

Parameters

color (int, str) –

The colors can be specified by their index, their full name, or the first letter. Available colors are:

1	`'b'`	blue
2	`'r'`	red
3	`'y'`	yellow
4	`'p'`	purple
5	`'g'`	green
6	`'t'`	turquois
7	`'o'`	orange
8	`'l'`	light green

Returns

color_hex – pyfar default color as HEX string

Return type

str

pyfar.plot.context(style='light', after_reset=False)[source]¶

Context manager for using plot styles temporarily.

This context manager supports the two pyfar styles light and dark. It is a wrapper for matplotlib.pyplot.style.context().

Parameters

style (str, dict, Path or list) –

A style specification. Valid options are:

str	The name of a style or a path/URL to a style file. For a list of available style names, see `matplotlib.style.available`.
dict	Dictionary with valid key/value pairs for `matplotlib.rcParams`.
Path	A path-like object which is a path to a style file.
list	A list of style specifiers (str, Path or dict) applied from first to last in the list.

after_reset (bool) – If True, apply style after resetting settings to their defaults; otherwise, apply style on top of the current settings.

See also

pyfar.plot.plotstyle

Examples

Generate customizable subplots with the default pyfar plot style

>>> import pyfar as pf
>>> import matplotlib.pyplot as plt
>>> with pf.plot.context():
>>>     fig, ax = plt.subplots(2, 1)
>>>     pf.plot.time(pf.Signal([0, 1, 0, -1], 44100), ax=ax[0])

pyfar.plot.custom_subplots(signal, plots, ax=None, style='light', **kwargs)[source]¶

Plot multiple pyfar plots with a custom layout and default parameters.

The plots are passed as a list of pyfar.plot function handles. The subplot layout is taken from the shape of that list (see example below).

Parameters

signal (Signal) – The input data to be plotted. Multidimensional data are flattened for plotting, e.g, a signal of signal.cshape = (2, 2) would be plotted in the order (0, 0), (0, 1), (1, 0), (1, 1).
plots (list, nested list) – Function handles for plotting.
ax (matplotlib.pyplot.axes) – Axes to plot on. The default is None, which uses the current axis or creates a new figure if none exists.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.plot().

Returns

ax – List of axes handles

Return type

matplotlib.pyplot.axes

Examples

Generate a two by two subplot layout

>>> import pyfar as pf
>>> impulse = pf.signals.impulse(100, 10)
>>> plots = [[pf.plot.time, pf.plot.phase],
...          [pf.plot.freq, pf.plot.group_delay]]
>>> pf.plot.custom_subplots(impulse, plots)

(Source code, png, hires.png, pdf)

pyfar.plot.freq(signal, dB=True, log_prefix=None, log_reference=1, freq_scale='log', ax=None, style='light', xscale=None, **kwargs)[source]¶

Plot the magnitude spectrum.

Plots abs(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.plot().

Parameters

signal (Signal, FrequencyData) – The input data to be plotted. Multidimensional data are flattened for plotting, e.g, a signal of signal.cshape = (2, 2) would be plotted in the order (0, 0), (0, 1), (1, 0), (1, 1).
dB (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(abs(signal.freq) / log_reference) is used. The default is True.
log_prefix (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer, float) – Reference for calculating the logarithmic frequency data. The default is 1.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
ax (matplotlib.pyplot.axes) – Axes to plot on. The default is None, which uses the current axis or creates a new figure if none exists.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
xscale (str) –

Deprecated since version 0.4.0.

This parameter was replaced by the more explicit freq_scale, which has the same functionality. If not None, it overwrites freq_scale. It is kept for backwards compatibility until pyfar version 0.6.0.

The default is None.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.plot().

Returns

ax – Axes or array of axes containing the plot.

Return type

matplotlib.pyplot.axes

Example

>>> import pyfar as pf
>>> sine = pf.signals.sine(100, 4410)
>>> pf.plot.freq(sine)

(Source code, png, hires.png, pdf)

pyfar.plot.freq_2d(signal, dB=True, log_prefix=None, log_reference=1, freq_scale='log', indices=None, orientation='vertical', cmap=<matplotlib.colors.ListedColormap object>, colorbar=True, ax=None, style='light', **kwargs)[source]¶

2D color coded plot of magnitude spectra.

Plots abs(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.pcolormesh().

Parameters

signal (Signal, FrequencyData) – The input data to be plotted. signal.cshape must be (m, ) with m>1.
dB (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(abs(signal.freq) / log_reference) is used. The default is True.
log_prefix (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer, float) – Reference for calculating the logarithmic frequency data. The default is 1.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
indices (array like, optional) – Points at which the channels of signal were sampled (e.g. azimuth angles or x values). indices must be monotonously increasing/ decreasing and have as many entries as signal has channels. The default is 'None' which labels the N channels in signal from 0 to N-1.
orientation (string, optional) –

'vertical'
The channels of signal will be plotted as as vertical lines.

'horizontal'
The channels of signal will be plotted as horizontal lines.

The default is 'vertical'
colorbar (bool, optional) – Control the colorbar. The default is True, which adds a colorbar to the plot. False omits the colorbar.
ax (matplotlib.pyplot.axes) –
Axes to plot on.

None
Use the current axis, or create a new axis (and figure) if there is none.

ax
If a single axis is passed, this is used for plotting. If colorbar is True the space for the colorbar is taken from this axis.

[ax, ax]
If a list or array of two axes is passed, the first is used to plot the data and the second to plot the colorbar. In this case colorbar must be True.

The default is None.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.pcolormesh().

Returns

ax (matplotlib.pyplot.axes) – If colorbar is True an array of two axes is returned. The first is the axis on which the data is plotted, the second is the axis of the colorbar. If colorbar is False, only the axis on which the data is plotted is returned.
quad_mesh (QuadMesh) – The Matplotlib quad mesh collection. This can be used to manipulate the way the data is displayed, e.g., by limiting the range of the colormap by quad_mesh.set_clim(). It can also be used to generate a colorbar by cb = fig.colorbar(quad_mesh, ...).
colorbar (Colorbar) – The Matplotlib colorbar object if colorbar is True and None otherwise. This can be used to control the appearance of the colorbar, e.g., the label can be set by colorbar.set_label().

Example

Plot a 25-channel impulse signal with different delays and amplitudes.

>>> import pyfar as pf
>>> import numpy as np
>>> impulses = pf.signals.impulse(
...     2048, np.arange(0, 25), np.linspace(1, .5, 25))
>>> pf.plot.freq_2d(impulses, dB=False)

(Source code, png, hires.png, pdf)

pyfar.plot.freq_group_delay(signal, dB=True, log_prefix=None, log_reference=1, unit=None, freq_scale='log', ax=None, style='light', xscale=None, **kwargs)[source]¶

Plot the magnitude and group delay spectrum (2 by 1 subplot).

Plots abs(signal.freq) and pyfar.dsp.group_delay(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.plot().

Parameters

signal (Signal) – The input data to be plotted. Multidimensional data are flattened for plotting, e.g, a signal of signal.cshape = (2, 2) would be plotted in the order (0, 0), (0, 1), (1, 0), (1, 1).
dB (bool) – Flag to plot the logarithmic magnitude spectrum. The default is True.
log_prefix (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer) – Reference for calculating the logarithmic frequency data. The default is 1.
unit (str) – Unit of the group delay. Can be 's', 'ms', 'mus', or 'samples'. The default is None, which sets the unit to s (seconds), ms (milliseconds), or mus (microseconds) depending on the data.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
ax (matplotlib.pyplot.axes) – Array or list with two axes to plot on. The default is None, which uses the current axis or creates a new figure if none exists.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
xscale (str) –

Deprecated since version 0.4.0.

This parameter was replaced by the more explicit freq_scale, which has the same functionality. If not None, it overwrites freq_scale. It is kept for backwards compatibility until pyfar version 0.6.0.

The default is None.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.plot().

Returns

ax – Axes or array of axes containing the plot.

Return type

matplotlib.pyplot.axes

Examples

>>> import pyfar as pf
>>> impulse = pf.signals.impulse(100, 10)
>>> pf.plot.freq_group_delay(impulse, unit='samples')

(Source code, png, hires.png, pdf)

pyfar.plot.freq_group_delay_2d(signal, dB=True, log_prefix=None, log_reference=1, unit=None, freq_scale='log', indices=None, orientation='vertical', cmap=<matplotlib.colors.ListedColormap object>, colorbar=True, ax=None, style='light', **kwargs)[source]¶

2D color coded plot of magnitude spectra and group delay (2 by 1 subplot).

Plots abs(signal.freq) and pyfar.dsp.group_delay(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.pcolormesh().

Parameters

signal (Signal) – The input data to be plotted. signal.cshape must be (m, ) with m>1.
dB (bool) – Flag to plot the logarithmic magnitude spectrum. The default is True.
log_prefix (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer) – Reference for calculating the logarithmic frequency data. The default is 1.
unit (str) – Unit of the group delay. Can be 's', 'ms', 'mus', or 'samples'. The default is None, which sets the unit to s (seconds), ms (milliseconds), or mus (microseconds) depending on the data.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
indices (array like, optional) – Points at which the channels of signal were sampled (e.g. azimuth angles or x values). indices must be monotonously increasing/ decreasing and have as many entries as signal has channels. The default is 'None' which labels the N channels in signal from 0 to N-1.
orientation (string, optional) –

'vertical'
The channels of signal will be plotted as as vertical lines.

'horizontal'
The channels of signal will be plotted as horizontal lines.

The default is 'vertical'
colorbar (bool, optional) – Control the colorbar. The default is True, which adds a colorbar to the plot. False omits the colorbar.
ax (matplotlib.pyplot.axes) –
Axes to plot on.

None
Use the current axis, or create a new axis (and figure) if there is none.

[ax, ax]
Two axes to plot on. Space for the colorbar of each plot is taken from the provided axes.

The default is None.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.pcolormesh().

Returns

ax (matplotlib.pyplot.axes) – If colorbar is True an array of four axes is returned. The first two are the axis on which the data is plotted, the last two are the axis of the colorbar. If colorbar is False, only the axes on which the data is plotted is returned.
quad_mesh (QuadMesh) – The Matplotlib quad mesh collection. This can be used to manipulate the way the data is displayed, e.g., by limiting the range of the colormap by quad_mesh.set_clim(). It can also be used to generate a colorbar by cb = fig.colorbar(quad_mesh, ...).
colorbar (Colorbar) – The Matplotlib colorbar object if colorbar is True and None otherwise. This can be used to control the appearance of the colorbar, e.g., the label can be set by colorbar.set_label().

Examples

Plot a 25-channel impulse signal with different delays and amplitudes.

>>> import pyfar as pf
>>> import numpy as np
>>> impulses = pf.signals.impulse(
...     2048, np.arange(0, 25), np.linspace(1, .5, 25))
>>> pf.plot.freq_group_delay_2d(impulses, dB=False, unit="samples")

(Source code, png, hires.png, pdf)

pyfar.plot.freq_phase(signal, dB=True, log_prefix=None, log_reference=1, freq_scale='log', deg=False, unwrap=False, ax=None, style='light', xscale=None, **kwargs)[source]¶

Plot the magnitude and phase spectrum (2 by 1 subplot).

Plots abs(signal.freq) and angle(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.plot().

Parameters

signal (Signal, FrequencyData) – The input data to be plotted. Multidimensional data are flattened for plotting, e.g, a signal of signal.cshape = (2, 2) would be plotted in the order (0, 0), (0, 1), (1, 0), (1, 1).
dB (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(abs(signal.freq) / log_reference) is used. The default is True.
log_prefix (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer) – Reference for calculating the logarithmic frequency data. The default is 1.
deg (bool) – Flag to plot the phase in degrees. The default is False.
unwrap (bool, str) – True to unwrap the phase or '360' to unwrap the phase to 2 pi. The default is False.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
ax (matplotlib.pyplot.axes) – Array or list with two axes to plot on. The default is None, which uses the current axis or creates a new figure if none exists.
style (str) – light or dark to use the pyfar plot styles or style from matplotlib.style.available. The default is light.
xscale (str) –

Deprecated since version 0.4.0.

This parameter was replaced by the more explicit freq_scale, which has the same functionality. If not None, it overwrites freq_scale. It is kept for backwards compatibility until pyfar version 0.6.0.

The default is None.
**kwargs – Keyword arguments that are forwarded to matplotlib.pyplot.plot

Returns

ax – Axes or array of axes containing the plot.

Return type

matplotlib.pyplot.axes

Examples

>>> import pyfar as pf
>>> impulse = pf.signals.impulse(100, 10)
>>> pf.plot.freq_phase(impulse, unwrap=True)

(Source code, png, hires.png, pdf)

pyfar.plot.freq_phase_2d(signal, dB=True, log_prefix=None, log_reference=1, freq_scale='log', deg=False, unwrap=False, indices=None, orientation='vertical', cmap=<matplotlib.colors.ListedColormap object>, colorbar=True, ax=None, style='light', **kwargs)[source]¶

2D color coded plot of magnitude and phase spectra (2 by 1 subplot).

Plots abs(signal.freq) and angle(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.pcolormesh().

Parameters

signal (Signal, FrequencyData) – The input data to be plotted. signal.cshape must be (m, ) with m>1.
dB (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(abs(signal.freq) / log_reference) is used. The default is True.
log_prefix (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer) – Reference for calculating the logarithmic frequency data. The default is 1.
deg (bool) – Flag to plot the phase in degrees. The default is False.
unwrap (bool, str) – True to unwrap the phase or '360' to unwrap the phase to 2 pi. The default is False.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
indices (array like, optional) – Points at which the channels of signal were sampled (e.g. azimuth angles or x values). indices must be monotonously increasing/ decreasing and have as many entries as signal has channels. The default is 'None' which labels the N channels in signal from 0 to N-1.
orientation (string, optional) –

'vertical'
The channels of signal will be plotted as as vertical lines.

'horizontal'
The channels of signal will be plotted as horizontal lines.

The default is 'vertical'
colorbar (bool, optional) – Control the colorbar. The default is True, which adds a colorbar to the plot. False omits the colorbar.
ax (matplotlib.pyplot.axes) –
Axes to plot on.

None
Use the current axis, or create a new axis (and figure) if there is none.

[ax, ax]
Two axes to plot on. Space for the colorbar of each plot is taken from the provided axes.

The default is None.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.pcolormesh().

Returns

ax (matplotlib.pyplot.axes) – If colorbar is True an array of four axes is returned. The first two are the axis on which the data is plotted, the last two are the axis of the colorbar. If colorbar is False, only the axes on which the data is plotted is returned.
quad_mesh (QuadMesh) – The Matplotlib quad mesh collection. This can be used to manipulate the way the data is displayed, e.g., by limiting the range of the colormap by quad_mesh.set_clim(). It can also be used to generate a colorbar by cb = fig.colorbar(quad_mesh, ...).
colorbar (Colorbar) – The Matplotlib colorbar object if colorbar is True and None otherwise. This can be used to control the appearance of the colorbar, e.g., the label can be set by colorbar.set_label().

Examples

Plot a 25-channel impulse signal with different delays and amplitudes.

>>> import pyfar as pf
>>> import numpy as np
>>> impulses = pf.signals.impulse(
...     2048, np.arange(0, 25), np.linspace(1, .5, 25))
>>> pf.plot.freq_phase_2d(impulses, dB=False, unwrap=True,
...                       freq_scale="linear")

(Source code, png, hires.png, pdf)

pyfar.plot.group_delay(signal, unit=None, freq_scale='log', ax=None, style='light', xscale=None, **kwargs)[source]¶

Plot the group delay.

Plots pyfar.dsp.group_delay(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.plot().

Parameters

signal (Signal) – The input data to be plotted. Multidimensional data are flattened for plotting, e.g, a signal of signal.cshape = (2, 2) would be plotted in the order (0, 0), (0, 1), (1, 0), (1, 1).
unit (str, None) – Unit of the group delay. Can be 's', 'ms', 'mus', or 'samples'. The default is None, which sets the unit to s (seconds), ms (milliseconds), or mus (microseconds) depending on the data.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
ax (matplotlib.pyplot.axes) – Axes to plot on. The default is None, which uses the current axis or creates a new figure if none exists.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
xscale (str) –

Deprecated since version 0.4.0.

This parameter was replaced by the more explicit freq_scale, which has the same functionality. If not None, it overwrites freq_scale. It is kept for backwards compatibility until pyfar version 0.6.0.

The default is None.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.plot().

Returns

ax – Axes or array of axes containing the plot.

Return type

matplotlib.pyplot.axes

Examples

>>> import pyfar as pf
>>> impulse = pf.signals.impulse(100, 10)
>>> pf.plot.group_delay(impulse, unit='samples')

(Source code, png, hires.png, pdf)

pyfar.plot.group_delay_2d(signal, unit=None, freq_scale='log', indices=None, orientation='vertical', cmap=<matplotlib.colors.ListedColormap object>, colorbar=True, ax=None, style='light', **kwargs)[source]¶

2D color coded plot of the group delay.

Plots pyfar.dsp.group_delay(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.pcolormesh().

Parameters

signal (Signal) – The input data to be plotted. signal.cshape must be (m, ) with m>1.
unit (str, None) – Unit of the group delay. Can be 's', 'ms', 'mus', or 'samples'. The default is None, which sets the unit to s (seconds), ms (milliseconds), or mus (microseconds) depending on the data.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
indices (array like, optional) – Points at which the channels of signal were sampled (e.g. azimuth angles or x values). indices must be monotonously increasing/ decreasing and have as many entries as signal has channels. The default is 'None' which labels the N channels in signal from 0 to N-1.
orientation (string, optional) –

'vertical'
The channels of signal will be plotted as as vertical lines.

'horizontal'
The channels of signal will be plotted as horizontal lines.

The default is 'vertical'
colorbar (bool, optional) – Control the colorbar. The default is True, which adds a colorbar to the plot. False omits the colorbar.
ax (matplotlib.pyplot.axes) –
Axes to plot on.

None
Use the current axis, or create a new axis (and figure) if there is none.

ax
If a single axis is passed, this is used for plotting. If colorbar is True the space for the colorbar is taken from this axis.

[ax, ax]
If a list or array of two axes is passed, the first is used to plot the data and the second to plot the colorbar. In this case colorbar must be True.

The default is None.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.pcolormesh().

Returns

ax (matplotlib.pyplot.axes) – If colorbar is True an array of four axes is returned. The first two are the axis on which the data is plotted, the last two are the axis of the colorbar. If colorbar is False, only the axes on which the data is plotted is returned.
quad_mesh (QuadMesh) – The Matplotlib quad mesh collection. This can be used to manipulate the way the data is displayed, e.g., by limiting the range of the colormap by quad_mesh.set_clim(). It can also be used to generate a colorbar by cb = fig.colorbar(quad_mesh, ...).
colorbar (Colorbar) – The Matplotlib colorbar object if colorbar is True and None otherwise. This can be used to control the appearance of the colorbar, e.g., the label can be set by colorbar.set_label().

Example

Plot a 25-channel impulse signal with different delays and amplitudes.

>>> import pyfar as pf
>>> import numpy as np
>>> impulses = pf.signals.impulse(
...     2048, np.arange(0, 25), np.linspace(1, .5, 25))
>>> pf.plot.group_delay_2d(impulses, unit="samples")

(Source code, png, hires.png, pdf)

pyfar.plot.phase(signal, deg=False, unwrap=False, freq_scale='log', ax=None, style='light', xscale=None, **kwargs)[source]¶

Plot the phase of the spectrum.

Plots angle(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.plot().

Parameters

signal (Signal, FrequencyData) – The input data to be plotted. Multidimensional data are flattened for plotting, e.g, a signal of signal.cshape = (2, 2) would be plotted in the order (0, 0), (0, 1), (1, 0), (1, 1).
deg (bool) – Plot the phase in degrees. The default is False, which plots the phase in radians.
unwrap (bool, str) – True to unwrap the phase or '360' to unwrap the phase to 2 pi. The default is False, which plots the wrapped phase.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
ax (matplotlib.pyplot.axes object) – Axes to plot on. The default is None, which uses the current axis or creates a new figure if none exists.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
xscale (str) –

Deprecated since version 0.4.0.

This parameter was replaced by the more explicit freq_scale, which has the same functionality. If not None, it overwrites freq_scale. It is kept for backwards compatibility until pyfar version 0.6.0.

The default is None.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.plot().

Returns

ax – Axes or array of axes containing the plot.

Return type

matplotlib.pyplot.axes

Example

>>> import pyfar as pf
>>> impulse = pf.signals.impulse(100, 10)
>>> pf.plot.phase(impulse, unwrap=True)

(Source code, png, hires.png, pdf)

pyfar.plot.phase_2d(signal, deg=False, unwrap=False, freq_scale='log', indices=None, orientation='vertical', cmap=<matplotlib.colors.ListedColormap object>, colorbar=True, ax=None, style='light', **kwargs)[source]¶

2D color coded plot of phase spectra.

Plots angle(signal.freq) and passes keyword arguments (kwargs) to matplotlib.pyplot.pcolormesh().

Parameters

signal (Signal, FrequencyData) – The input data to be plotted. signal.cshape must be (m, ) with m>1.
deg (bool) – Plot the phase in degrees. The default is False, which plots the phase in radians.
unwrap (bool, str) – True to unwrap the phase or '360' to unwrap the phase to 2 pi. The default is False, which plots the wrapped phase.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
indices (array like, optional) – Points at which the channels of signal were sampled (e.g. azimuth angles or x values). indices must be monotonously increasing/ decreasing and have as many entries as signal has channels. The default is 'None' which labels the N channels in signal from 0 to N-1.
orientation (string, optional) –

'vertical'
The channels of signal will be plotted as as vertical lines.

'horizontal'
The channels of signal will be plotted as horizontal lines.

The default is 'vertical'
colorbar (bool, optional) – Control the colorbar. The default is True, which adds a colorbar to the plot. False omits the colorbar.
ax (matplotlib.pyplot.axes) –
Axes to plot on.

None
Use the current axis, or create a new axis (and figure) if there is none.

ax
If a single axis is passed, this is used for plotting. If colorbar is True the space for the colorbar is taken from this axis.

[ax, ax]
If a list or array of two axes is passed, the first is used to plot the data and the second to plot the colorbar. In this case colorbar must be True.

The default is None.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.pcolormesh().

Returns

ax (matplotlib.pyplot.axes) – If colorbar is True an array of two axes is returned. The first is the axis on which the data is plotted, the second is the axis of the colorbar. If colorbar is False, only the axis on which the data is plotted is returned.
quad_mesh (QuadMesh) – The Matplotlib quad mesh collection. This can be used to manipulate the way the data is displayed, e.g., by limiting the range of the colormap by quad_mesh.set_clim(). It can also be used to generate a colorbar by cb = fig.colorbar(quad_mesh, ...).
colorbar (Colorbar) – The Matplotlib colorbar object if colorbar is True and None otherwise. This can be used to control the appearance of the colorbar, e.g., the label can be set by colorbar.set_label().

Example

Plot a 25-channel impulse signal with different delays and amplitudes.

>>> import pyfar as pf
>>> import numpy as np
>>> impulses = pf.signals.impulse(
...     2048, np.arange(0, 25), np.linspace(1, .5, 25))
>>> pf.plot.phase_2d(impulses, unwrap=True, freq_scale="linear")

(Source code, png, hires.png, pdf)

pyfar.plot.plotstyle(style='light')[source]¶

Get the fullpath of the pyfar plotstyles light or dark.

The plotstyles are defined by mplstyle files, which is Matplotlibs format to define styles. By default, pyfar uses the light plotstyle.

Parameters: style (str) – light, or dark
Returns: style – Full path to the pyfar plotstyle.
Return type: str

See also

pyfar.plot.use, pyfar.plot.context

pyfar.plot.shortcuts(show=True)[source]¶

Show and return keyboard shortcuts for interactive figures.

Note that shortcuts are only available if using an interactive backend in Matplotlib, e.g., by %matplotlib qt.

Parameters: show (bool, optional) – Print the keyboard shortcuts to the default console. The default is True.
Returns: short_cuts – Dictionary that contains all the shortcuts.
Return type: dict

pyfar.plot.spectrogram(signal, dB=True, log_prefix=None, log_reference=1, freq_scale='linear', unit=None, window='hann', window_length=1024, window_overlap_fct=0.5, cmap=<matplotlib.colors.ListedColormap object>, colorbar=True, ax=None, style='light', yscale=None, **kwargs)[source]¶

Plot blocks of the magnitude spectrum versus time.

Parameters

signal (Signal) – The input data to be plotted. Multidimensional data are flattened for plotting, e.g, a signal of signal.cshape = (2, 2) would be plotted in the order (0, 0), (0, 1), (1, 0), (1, 1).
dB (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(abs(signal.freq) / log_reference) is used. The default is True.
log_prefix (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer) – Reference for calculating the logarithmic frequency data. The default is 1.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is linear.
unit (str, None) – Unit of the time axis. Can be 's', 'ms', 'mus', or 'samples'. The default is None, which sets the unit to s (seconds), ms (milliseconds), or mus (microseconds) depending on the data.
window (str) – Specifies the window that is applied to each block of the time data before applying the Fourier transform. The default is hann. See scipy.signal.get_window for a list of possible windows.
window_length (integer) – Specifies the window/block length in samples. The default is 1024.
window_overlap_fct (double) – Ratio of indices to overlap between blocks [0…1]. The default is 0.5, which would result in 512 samples overlap for a window length of 1024 samples.
cmap (matplotlib.colors.Colormap(name, N=256)) – Colormap for spectrogram. Defaults to matplotlibs magma colormap.
colorbar (bool, optional) – Control the colorbar. The default is True, which adds a colorbar to the plot. False omits the colorbar.
ax (matplotlib.pyplot.axes) –
Axes to plot on.

None
Use the current axis, or create a new axis (and figure) if there is none.

ax
If a single axis is passed, this is used for plotting. If colorbar is True the space for the colorbar is taken from this axis.

[ax, ax]
If a list or array of two axes is passed, the first is used to plot the data and the second to plot the colorbar. In this case colorbar must be True.

The default is None.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
yscale (str) –

Deprecated since version 0.4.0.

This parameter was replaced by the more explicit freq_scale, which has the same functionality. If not None, it overwrites freq_scale. It is kept for backwards compatibility until pyfar version 0.6.0.

The default is None.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.pcolormesh().

Returns

ax (matplotlib.pyplot.axes) – If colorbar is True an array of two axes is returned. The first is the axis on which the data is plotted, the second is the axis of the colorbar. If colorbar is False, only the axis on which the data is plotted is returned.
quad_mesh (QuadMesh) – The Matplotlib quad mesh collection. This can be used to manipulate the way the data is displayed, e.g., by limiting the range of the colormap by quad_mesh.set_clim(). It can also be used to generate a colorbar by cb = fig.colorbar(quad_mesh, ...).
colorbar (Colorbar) – The Matplotlib colorbar object if colorbar is True and None otherwise. This can be used to control the appearance of the colorbar, e.g., the label can be set by colorbar.set_label().

Example

Plot the spectrogram of a linear sweep

>>> import pyfar as pf
>>> sweep = pf.signals.linear_sweep_time(2**14, [0, 22050])
>>> pf.plot.spectrogram(sweep)

(Source code, png, hires.png, pdf)

pyfar.plot.time(signal, dB=False, log_prefix=20, log_reference=1, unit=None, ax=None, style='light', **kwargs)[source]¶

Plot the time signal.

Plots signal.time and passes keyword arguments (kwargs) to matplotlib.pyplot.plot().

Parameters

signal (Signal, TimeData) – The input data to be plotted. Multidimensional data are flattened for plotting, e.g, a signal of signal.cshape = (2, 2) would be plotted in the order (0, 0), (0, 1), (1, 0), (1, 1).
dB (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(signal.time / log_reference) is used. The default is False.
log_prefix (integer, float) – Prefix for calculating the logarithmic time data. The default is 20.
log_reference (integer) – Reference for calculating the logarithmic time data. The default is 1.
unit (str, None) – Unit of the time axis. Can be 's', 'ms', 'mus', or 'samples'. The default is None, which sets the unit to s (seconds), ms (milliseconds), or mus (microseconds) depending on the data.
ax (matplotlib.pyplot.axes) – Axes to plot on. The default is None, which uses the current axis or creates a new figure if none exists.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.plot().

Returns

ax – Axes or array of axes containing the plot.

Return type

matplotlib.pyplot.axes

Examples

>>> import pyfar as pf
>>> sine = pf.signals.sine(100, 4410)
>>> pf.plot.time(sine)

(Source code, png, hires.png, pdf)

pyfar.plot.time_2d(signal, dB=False, log_prefix=None, log_reference=1, unit=None, indices=None, orientation='vertical', cmap=<matplotlib.colors.ListedColormap object>, colorbar=True, ax=None, style='light', **kwargs)[source]¶

2D color coded plot of time signals.

Plots signal.time and passes keyword arguments (kwargs) to matplotlib.pyplot.pcolormesh().

Parameters

signal (Signal, TimeData) – The input data to be plotted. signal.cshape must be (m, ) with m>1.
dB (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(signal.time / log_reference) is used. The default is False.
log_prefix (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer) – Reference for calculating the logarithmic time data. The default is 1.
unit (str, None) – Unit of the time axis. Can be 's', 'ms', 'mus', or 'samples'. The default is None, which sets the unit to s (seconds), ms (milliseconds), or mus (microseconds) depending on the data.
indices (array like, optional) – Points at which the channels of signal were sampled (e.g. azimuth angles or x values). indices must be monotonously increasing/ decreasing and have as many entries as signal has channels. The default is 'None' which labels the N channels in signal from 0 to N-1.
orientation (string, optional) –

'vertical'
The channels of signal will be plotted as as vertical lines.

'horizontal'
The channels of signal will be plotted as horizontal lines.

The default is 'vertical'
colorbar (bool, optional) – Control the colorbar. The default is True, which adds a colorbar to the plot. False omits the colorbar.
ax (matplotlib.pyplot.axes) –
Axes to plot on.

None
Use the current axis, or create a new axis (and figure) if there is none.

ax
If a single axis is passed, this is used for plotting. If colorbar is True the space for the colorbar is taken from this axis.

[ax, ax]
If a list or array of two axes is passed, the first is used to plot the data and the second to plot the colorbar. In this case colorbar must be True.

The default is None.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.pcolormesh().

Returns

ax (matplotlib.pyplot.axes) – If colorbar is True an array of two axes is returned. The first is the axis on which the data is plotted, the second is the axis of the colorbar. If colorbar is False, only the axis on which the data is plotted is returned.
quad_mesh (QuadMesh) – The Matplotlib quad mesh collection. This can be used to manipulate the way the data is displayed, e.g., by limiting the range of the colormap by quad_mesh.set_clim(). It can also be used to generate a colorbar by cb = fig.colorbar(quad_mesh, ...).
colorbar (Colorbar) – The Matplotlib colorbar object if colorbar is True and None otherwise. This can be used to control the appearance of the colorbar, e.g., the label can be set by colorbar.set_label().

Examples

Plot a 25-channel impulse signal with different delays and amplitudes.

>>> import pyfar as pf
>>> import numpy as np
>>> impulses = pf.signals.impulse(
...     64, np.arange(0, 25), np.linspace(1, .5, 25))
>>> pf.plot.time_2d(impulses)

(Source code, png, hires.png, pdf)

pyfar.plot.time_freq(signal, dB_time=False, dB_freq=True, log_prefix_time=20, log_prefix_freq=None, log_reference=1, freq_scale='log', unit=None, ax=None, style='light', xscale=None, **kwargs)[source]¶

Plot the time signal and magnitude spectrum (2 by 1 subplot).

Plots signal.time and abs(signal.freq) passes keyword arguments (kwargs) to matplotlib.pyplot.plot().

Parameters

signal (Signal) – The input data to be plotted. Multidimensional data are flattened for plotting, e.g, a signal of signal.cshape = (2, 2) would be plotted in the order (0, 0), (0, 1), (1, 0), (1, 1).
dB_time (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(signal.time / log_reference) is used. The default is False.
dB_freq (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(abs(signal.freq) / log_reference) is used. The default is True.
log_prefix_time (integer, float) – Prefix for calculating the logarithmic time data. The default is 20.
log_prefix_freq (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer) – Reference for calculating the logarithmic time/frequency data. The default is 1.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
unit (str) – Unit of the time axis. Can be 's', 'ms', 'mus', or 'samples'. The default is None, which sets the unit to s (seconds), ms (milliseconds), or mus (microseconds) depending on the data.
ax (matplotlib.pyplot.axes) – Array or list with two axes to plot on. The default is None, which uses the current axis or creates a new figure if none exists.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
xscale (str) –

Deprecated since version 0.4.0.

This parameter was replaced by the more explicit freq_scale, which has the same functionality. If not None, it overwrites freq_scale. It is kept for backwards compatibility until pyfar version 0.6.0.

The default is None.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.plot().

Returns

ax – Axes or array of axes containing the plot.

Return type

matplotlib.pyplot.axes

Examples

>>> import pyfar as pf
>>> sine = pf.signals.sine(100, 4410)
>>> pf.plot.time_freq(sine)

(Source code, png, hires.png, pdf)

pyfar.plot.time_freq_2d(signal, dB_time=False, dB_freq=True, log_prefix_time=20, log_prefix_freq=None, log_reference=1, freq_scale='log', unit=None, indices=None, orientation='vertical', cmap=<matplotlib.colors.ListedColormap object>, colorbar=True, ax=None, style='light', **kwargs)[source]¶

2D color coded plot of time signals and magnitude spectra (2 by 1 subplot).

Plots signal.time and abs(signal.freq) passes keyword arguments (kwargs) to matplotlib.pyplot.pcolormesh().

Parameters

signal (Signal) – The input data to be plotted. signal.cshape must be (m, ) with m>1.
dB_time (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(signal.time / log_reference) is used. The default is False.
dB_freq (bool) – Indicate if the data should be plotted in dB in which case log_prefix * np.log10(abs(signal.freq) / log_reference) is used. The default is True.
log_prefix_time (integer, float) – Prefix for calculating the logarithmic time data. The default is 20.
log_prefix_freq (integer, float) – Prefix for calculating the logarithmic frequency data. The default is None, so 10 is chosen if signal.fft_norm is 'power' or 'psd' and 20 otherwise.
log_reference (integer) – Reference for calculating the logarithmic time/frequency data. The default is 1.
freq_scale (str) – linear or log to plot on a linear or logarithmic frequency axis. The default is log.
unit (str) – Unit of the time axis. Can be 's', 'ms', 'mus', or 'samples'. The default is None, which sets the unit to s (seconds), ms (milliseconds), or mus (microseconds) depending on the data.
indices (array like, optional) – Points at which the channels of signal were sampled (e.g. azimuth angles or x values). indices must be monotonously increasing/ decreasing and have as many entries as signal has channels. The default is 'None' which labels the N channels in signal from 0 to N-1.
orientation (string, optional) –

'vertical'
The channels of signal will be plotted as as vertical lines.

'horizontal'
The channels of signal will be plotted as horizontal lines.

The default is 'vertical'
colorbar (bool, optional) – Control the colorbar. The default is True, which adds a colorbar to the plot. False omits the colorbar.
ax (matplotlib.pyplot.axes) –
Axes to plot on.

None
Use the current axis, or create a new axis (and figure) if there is none.

[ax, ax]
Two axes to plot on. Space for the colorbar of each plot is taken from the provided axes.

The default is None.
style (str) – light or dark to use the pyfar plot styles or a plot style from matplotlib.style.available. The default is light.
**kwargs – Keyword arguments that are passed to matplotlib.pyplot.pcolormesh().

Returns

ax (matplotlib.pyplot.axes) – If colorbar is True an array of four axes is returned. The first two are the axis on which the data is plotted, the last two are the axis of the colorbar. If colorbar is False, only the axes on which the data is plotted is returned.
quad_mesh (QuadMesh) – The Matplotlib quad mesh collection. This can be used to manipulate the way the data is displayed, e.g., by limiting the range of the colormap by quad_mesh.set_clim(). It can also be used to generate a colorbar by cb = fig.colorbar(quad_mesh, ...).
colorbar (Colorbar) – The Matplotlib colorbar object if colorbar is True and None otherwise. This can be used to control the appearance of the colorbar, e.g., the label can be set by colorbar.set_label().

Examples

Plot a 25-channel impulse signal with different delays and amplitudes.

>>> import pyfar as pf
>>> import numpy as np
>>> impulses = pf.signals.impulse(
...     64, np.arange(0, 25), np.linspace(1, .5, 25))
>>> pf.plot.time_freq_2d(impulses, dB_freq=False)

(Source code, png, hires.png, pdf)

pyfar.plot.use(style='light')[source]¶

Use plot style settings from a style specification.

The style name of default is reserved for reverting back to the default style settings. This is a wrapper for matplotlib.style.use that supports the pyfar plot styles light and dark.

Parameters

style (str, dict, Path or list) –

A style specification. Valid options are:

str	The name of a style or a path/URL to a style file. For a list of available style names, see `matplotlib.style.available`.
dict	Dictionary with valid key/value pairs for `matplotlib.rcParams`.
Path	A path-like object which is a path to a style file.
list	A list of style specifiers (str, Path or dict) applied from first to last in the list.