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_group_delay`(signal[, dB, log_prefix, ...])	Plot the magnitude and group delay spectrum in a 2 by 1 subplot layout.
`freq_phase`(signal[, dB, log_prefix, ...])	Plot the magnitude and phase spectrum in a 2 by 1 subplot layout.
`group_delay`(signal[, unit, xscale, ax, style])	Plot the group delay.
`phase`(signal[, deg, unwrap, xscale, ax, style])	Plot the phase of the spectrum.
`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_freq`(signal[, dB_time, dB_freq, ...])	Plot the time signal and magnitude spectrum in a 2 by 1 subplot layout.
`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, xscale='log', ax=None, style='light', **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.
xscale (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.
**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_group_delay(signal, dB=True, log_prefix=None, log_reference=1, unit=None, xscale='log', ax=None, style='light', **kwargs)[source]¶

Plot the magnitude and group delay spectrum in a 2 by 1 subplot layout.

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) – 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 (milli seconds), or mus (micro seconds) depending on the data.
xscale (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.
**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_phase(signal, dB=True, log_prefix=None, log_reference=1, xscale='log', deg=False, unwrap=False, ax=None, style='light', **kwargs)[source]¶

Plot the magnitude and phase spectrum in a 2 by 1 subplot layout.

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.
xscale (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 figure ore creates a new one if no figure exists.
style (str) – light or dark to use the pyfar plot styles or style from matplotlib.style.available. The default is light.
**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

See also

matplotlib.pyplot.plot

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

Plot the group delay.

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 (milli seconds), or mus (micro seconds) depending on the data.
xscale (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.
**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.phase(signal, deg=False, unwrap=False, xscale='log', ax=None, style='light', **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.
xscale (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.
**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.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, yscale='linear', unit=None, window='hann', window_length=1024, window_overlap_fct=0.5, cmap=<matplotlib.colors.ListedColormap object>, colorbar=True, ax=None, style='light')[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.
yscale (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 (milli seconds), or mus (micro seconds) 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 points 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.

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(qm, ...).
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

>>> 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 (milli seconds), or mus (micro seconds) 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_freq(signal, dB_time=False, dB_freq=True, log_prefix_time=20, log_prefix_freq=None, log_reference=1, xscale='log', unit=None, ax=None, style='light', **kwargs)[source]¶

Plot the time signal and magnitude spectrum in a 2 by 1 subplot layout.

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.
xscale (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 (milli seconds), or mus (micro seconds) 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_freq(sine)

(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.

See also

pyfar.plot.plotstyle

Notes

This updates the rcParams with the settings from the style. rcParams not defined in the style are kept.

Examples

Permanently use the pyfar default plot style

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