API Reference

This part of the documentation details the complete BioSPPy API.

Packages

Modules

biosppy.plotting

This module provides utilities to plot data.

copyright:

  1. 2015-2023 by Instituto de Telecomunicacoes

license:

BSD 3-clause, see LICENSE for more details.

biosppy.plotting.color_palette(idx)[source]

Color palette to use throughout the biosppy package

Parameters:

idx (str or int) – identifier of color to use

Returns:

color_id (str) – hexadecimal color code chosen

biosppy.plotting.plot_abp(ts=None, raw=None, filtered=None, onsets=None, heart_rate_ts=None, heart_rate=None, path=None, show=False)[source]

Create a summary plot from the output of signals.abp.abp.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw ABP signal.

  • filtered (array) – Filtered ABP signal.

  • onsets (array) – Indices of ABP pulse onsets.

  • heart_rate_ts (array) – Heart rate time axis reference (seconds).

  • heart_rate (array) – Instantaneous heart rate (bpm).

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_acc(ts=None, raw=None, vm=None, sm=None, units=None, path=None, show=False)[source]

Create a summary plot from the output of signals.acc.acc.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw ACC signal.

  • vm (array) – Vector Magnitude feature of the signal.

  • sm (array) – Signal Magnitude feature of the signal

  • units (str, optional) – Units of the vertical axis. If provided, the plot title will include the units information. Default is None.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_bcg(ts=None, raw=None, filtered=None, jpeaks=None, templates_ts=None, templates=None, heart_rate_ts=None, heart_rate=None, path=None, show=False)[source]

Create a summary plot from the output of signals.bcg.bcg.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw ECG signal.

  • filtered (array) – Filtered ECG signal.

  • ipeaks (array) – I-peak location indices.

  • templates_ts (array) – Templates time axis reference (seconds).

  • templates (array) – Extracted heartbeat templates.

  • heart_rate_ts (array) – Heart rate time axis reference (seconds).

  • heart_rate (array) – Instantaneous heart rate (bpm).

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_biometrics(assessment=None, eer_idx=None, path=None, show=False)[source]

Create a summary plot of a biometrics test run.

Parameters:

  • assessment (dict) – Classification assessment results.

  • eer_idx (int, optional) – Classifier reference index for the Equal Error Rate.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_bvp(ts=None, raw=None, filtered=None, onsets=None, heart_rate_ts=None, heart_rate=None, path=None, show=False)[source]

Create a summary plot from the output of signals.bvp.bvp.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw BVP signal.

  • filtered (array) – Filtered BVP signal.

  • onsets (array) – Indices of BVP pulse onsets.

  • heart_rate_ts (array) – Heart rate time axis reference (seconds).

  • heart_rate (array) – Instantaneous heart rate (bpm).

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_clustering(data=None, clusters=None, path=None, show=False)[source]

Create a summary plot of a data clustering.

Parameters:

  • data (array) – An m by n array of m data samples in an n-dimensional space.

  • clusters (dict) – Dictionary with the sample indices (rows from data) for each cluster.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_ecg(ts=None, raw=None, filtered=None, rpeaks=None, templates_ts=None, templates=None, heart_rate_ts=None, heart_rate=None, units=None, path=None, show=False)[source]

Create a summary plot from the output of signals.ecg.ecg.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw ECG signal.

  • filtered (array) – Filtered ECG signal.

  • rpeaks (array) – R-peak location indices.

  • templates_ts (array) – Templates time axis reference (seconds).

  • templates (array) – Extracted heartbeat templates.

  • heart_rate_ts (array) – Heart rate time axis reference (seconds).

  • heart_rate (array) – Instantaneous heart rate (bpm).

  • units (str, optional) – Units of the vertical axis. If provided, the plot title will include the units information. Default is None.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_eda(ts=None, raw=None, filtered=None, edr=None, edl=None, onsets=None, peaks=None, amplitudes=None, units=None, path=None, show=False)[source]

Create a summary plot from the output of signals.eda.eda.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw EDA signal.

  • filtered (array) – Filtered EDA signal.

  • edr (array) – Electrodermal response signal.

  • edl (array) – Electrodermal level signal.

  • onsets (array) – Events onsets indices.

  • peaks (array) – Events peaks indices.

  • amplitudes (array) – Amplitudes location indices.

  • units (str, optional) – Units of the vertical axis. If provided, the plot title will include the units information. Default is None.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_eeg(ts=None, raw=None, filtered=None, labels=None, features_ts=None, theta=None, alpha_low=None, alpha_high=None, beta=None, gamma=None, plf_pairs=None, plf=None, path=None, show=False)[source]

Create a summary plot from the output of signals.eeg.eeg.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw EEG signal.

  • filtered (array) – Filtered EEG signal.

  • labels (list) – Channel labels.

  • features_ts (array) – Features time axis reference (seconds).

  • theta (array) – Average power in the 4 to 8 Hz frequency band; each column is one EEG channel.

  • alpha_low (array) – Average power in the 8 to 10 Hz frequency band; each column is one EEG channel.

  • alpha_high (array) – Average power in the 10 to 13 Hz frequency band; each column is one EEG channel.

  • beta (array) – Average power in the 13 to 25 Hz frequency band; each column is one EEG channel.

  • gamma (array) – Average power in the 25 to 40 Hz frequency band; each column is one EEG channel.

  • plf_pairs (list) – PLF pair indices.

  • plf (array) – PLF matrix; each column is a channel pair.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_emg(ts=None, sampling_rate=None, raw=None, filtered=None, onsets=None, processed=None, units=None, path=None, show=False)[source]

Create a summary plot from the output of signals.emg.emg.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • sampling_rate (int, float) – Sampling frequency (Hz).

  • raw (array) – Raw EMG signal.

  • filtered (array) – Filtered EMG signal.

  • onsets (array) – Indices of EMG pulse onsets.

  • processed (array, optional) – Processed EMG signal according to the chosen onset detector.

  • units (str, optional) – Units of the vertical axis. If provided, the plot title will include the units information. Default is None.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_filter(ftype='FIR', band='lowpass', order=None, frequency=None, sampling_rate=1000.0, log_xscale=True, path=None, show=True, **kwargs)[source]

Plot the frequency response of the filter specified with the given parameters.

Parameters:

  • ftype (str) –

    Filter type:

    • Finite Impulse Response filter (‘FIR’);

    • Butterworth filter (‘butter’);

    • Chebyshev filters (‘cheby1’, ‘cheby2’);

    • Elliptic filter (‘ellip’);

    • Bessel filter (‘bessel’).

  • band (str) –

    Band type:

    • Low-pass filter (‘lowpass’);

    • High-pass filter (‘highpass’);

    • Band-pass filter (‘bandpass’);

    • Band-stop filter (‘bandstop’).

  • order (int) – Order of the filter.

  • frequency (int, float, list, array) –

    Cutoff frequencies; format depends on type of band:

    • ’lowpass’ or ‘bandpass’: single frequency;

    • ’bandpass’ or ‘bandstop’: pair of frequencies.

  • sampling_rate (int, float, optional) – Sampling frequency (Hz).

  • log_xscale (bool, optional) – Whether to use log scale for x-axis.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

  • **kwargs (dict, optional) – Additional keyword arguments are passed to the underlying scipy.signal function.

biosppy.plotting.plot_hrv(rri, rri_trend=None, td_out=None, nl_out=None, fd_out=None, show=False)[source]

Create a summary plot of a HRV analysis.

Parameters:

  • rri (array) – RR-intervals (ms).

  • rri_trend (array, optional) – RR-intervals trend (ms).

  • td_out (dict) – Output of signals.hrv.timedomain.

  • nl_out (dict) – Output of signals.hrv.nonlinear.

  • fd_out (dict) – Output of signals.hrv.frequencyomain.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_hrv_fbands(frequencies=None, powers=None, fbands=None, method_name=None, legends=None, ax=None, show=False)[source]

Plots the power spectrum and highlights the defined frequency bands from the output of signals.hrv.compute_fbands.

Parameters:

  • frequencies (array) – Frequency axis.

  • powers (array) – Power spectrum values for the frequency axis.

  • fbands (dict, optional) – Dictionary containing the limits of the frequency bands.

  • method_name (str, optional) – Method that was used to compute the power spectrum.

  • legends (dict, optional) – Additional legend elements.

  • ax (axis, optional) – Plot Axis to use.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_hrv_hist(rri=None, bins=None, q_hist=None, hti=None, tinn=None, ax=None, show=False)[source]

Plots the RRI histogram with the corresponding geometrical HRV features from the output of signals.hrv.compute_geometrical.

Parameters:

  • rri (array) – RR-intervals (ms).

  • bins (array) – Histogram bins.

  • q_hist (array) – Multilinear function fitted to the histogram.

  • hti (float) – HTI - HRV triangular index - Integral of the density of the RR interval histogram divided by its height.

  • tinn (float) – TINN - Baseline width of RR interval histogram (ms).

  • ax (axis, optional) – Plot Axis to use.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_pcg(ts=None, raw=None, filtered=None, peaks=None, heart_sounds=None, heart_rate_ts=None, inst_heart_rate=None, units=None, path=None, show=False)[source]

Create a summary plot from the output of signals.pcg.pcg.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw PCG signal.

  • filtered (array) – Filtered PCG signal.

  • peaks (array) – Peak location indices.

  • heart_sounds (array) – Classification of peaks as S1 or S2

  • heart_rate_ts (array) – Heart rate time axis reference (seconds).

  • inst_heart_rate (array) – Instantaneous heart rate (bpm).

  • units (str, optional) – Units of the vertical axis. If provided, the plot title will include the units information. Default is None.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_poincare(rri=None, s=None, sd1=None, sd2=None, legends=None, ax=None, show=False)[source]

Plot a Poincaré plot of a series of RR intervals (RRI[i+1] vs. RRI[i]) from the output of signals.hrv.compute_poincare.

Parameters:

  • rri (array) – RR-intervals (ms).

  • s (float) – S - Area of the ellipse of the Poincaré plot (ms^2).

  • sd1 (float) – SD1 - Poincaré plot standard deviation perpendicular to the identity line (ms).

  • sd2 (float) – SD2 - Poincaré plot standard deviation along the identity line (ms).

  • legends (dict, optional) – Dictionary of features to add to the plot legend.

  • ax (axis, optional) – Plot Axis to use.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_ppg(ts=None, raw=None, filtered=None, peaks=None, templates_ts=None, templates=None, heart_rate_ts=None, heart_rate=None, units=None, path=None, show=False)[source]

Create a summary plot from the output of signals.ppg.ppg.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw PPG signal.

  • filtered (array) – Filtered PPG signal.

  • peaks (array) – Indices of PPG pulse peaks.

  • templates_ts (array) – Templates time axis reference (seconds).

  • templates (array) – Extracted PPG templates.

  • heart_rate_ts (array) – Heart rate time axis reference (seconds).

  • heart_rate (array) – Instantaneous heart rate (bpm).

  • units (str, optional) – Units of the vertical axis. If provided, the plot title will include the units information. Default is None.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_resp(ts=None, raw=None, filtered=None, zeros=None, resp_rate_ts=None, resp_rate=None, units=None, path=None, show=False)[source]

Create a summary plot from the output of signals.ppg.ppg.

Parameters:

  • ts (array) – Signal time axis reference (seconds).

  • raw (array) – Raw Resp signal.

  • filtered (array) – Filtered Resp signal.

  • zeros (array) – Indices of Respiration zero crossings.

  • resp_rate_ts (array) – Respiration rate time axis reference (seconds).

  • resp_rate (array) – Instantaneous respiration rate (Hz).

  • units (str, optional) – Units of the vertical axis. If provided, the plot title will include the units information. Default is None.

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_rri(rri, rri_trend=None, legends=None, ax=None, show=False)[source]

Plot a series of RR intervals.

Parameters:

  • rri (array) – RR-intervals (ms).

  • rri_trend (array, optional) – RR-intervals trend (ms).

  • legends (dict, optional) – Dictionary of features to add to the plot legend.

  • ax (axis, optional) – Plot Axis to use.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.plotting.plot_spectrum(signal=None, sampling_rate=1000.0, path=None, show=True)[source]

Plot the power spectrum of a signal (one-sided).

Parameters:

  • signal (array) – Input signal.

  • sampling_rate (int, float, optional) – Sampling frequency (Hz).

  • path (str, optional) – If provided, the plot will be saved to the specified file.

  • show (bool, optional) – If True, show the plot immediately.

biosppy.utils

This module provides several frequently used functions and hacks.

copyright:

  1. 2015-2018 by Instituto de Telecomunicacoes

license:

BSD 3-clause, see LICENSE for more details.

class biosppy.utils.ReturnTuple(values, names=None)[source]

Bases: tuple

A named tuple to use as a hybrid tuple-dict return object.

Parameters:

  • values (iterable) – Return values.

  • names (iterable, optional) – Names for return values.

Raises:

  • ValueError – If the number of values differs from the number of names.

  • ValueError – If any of the items in names: * contain non-alphanumeric characters; * are Python keywords; * start with a number; * are duplicates.

append(new_values: (<class 'int'>, <class 'float'>, <class 'complex'>, <class 'str'>, typing.Collection, <Mock id='140310640371888'>), new_keys=None)[source]

Returns a new ReturnTuple with the new values and keys appended to the original object.

Parameters:

  • new_values (int, float, list, tuple, dict, array) – Values to append. If given a dict and new_keys is None, the correspondent keys and values will be used.

  • new_keys (str, list, tuple, optional) – Keys to append.

Returns:

object (ReturnTuple) – A ReturnTuple with the values and keys appended.

as_dict()[source]

Convert to an ordered dictionary.

Returns:

out (OrderedDict) – An OrderedDict representing the return values.

delete(key)[source]

Returns a ReturnTuple without the specified key.

Parameters:

key (str) – ReturnTuple key to be deleted.

Returns:

object (ReturnTuple) – The ReturnTuple with the key removed.

join(new_tuple)[source]

Returns a ReturnTuple with the new ReturnTuple appended.

Parameters:

new_tuple (ReturnTuple) – ReturnTuple to be joined.

Returns:

object (ReturnTuple) – The joined ReturnTuple.

keys()[source]

Return the value names.

Returns:

out (list) – The keys in the mapping.

biosppy.utils.fileparts(path)[source]

split a file path into its directory, name, and extension.

Parameters:

path (str) – Input file path.

Returns:

  • dirname (str) – File directory.

  • fname (str) – File name.

  • ext (str) – File extension.

Notes

  • Removes the dot (‘.’) from the extension.

biosppy.utils.fullfile(*args)[source]

Join one or more file path components, assuming the last is the extension.

Parameters:

*args (list, optional) – Components to concatenate.

Returns:

fpath (str) – The concatenated file path.

biosppy.utils.highestAveragesAllocator(votes, k, divisor='dHondt', check=False)[source]

Allocate k seats proportionally using the Highest Averages Method.

Parameters:

  • votes (list) – Number of votes for each class/party/cardinal.

  • k (int) – Total number o seats to allocate.

  • divisor (str, optional) – Divisor method; one of ‘dHondt’, ‘Huntington-Hill’, ‘Sainte-Lague’, ‘Imperiali’, or ‘Danish’.

  • check (bool, optional) – If True, limits the number of seats to the total number of votes.

Returns:

seats (list) – Number of seats for each class/party/cardinal.

biosppy.utils.normpath(path)[source]

Normalize a path.

Parameters:

path (str) – The path to normalize.

Returns:

npath (str) – The normalized path.

biosppy.utils.random_fraction(indx, fraction, sort=True)[source]

Select a random fraction of an input list of elements.

Parameters:

  • indx (list, array) – Elements to partition.

  • fraction (int, float) – Fraction to select.

  • sort (bool, optional) – If True, output lists will be sorted.

Returns:

  • use (list, array) – Selected elements.

  • unuse (list, array) – Remaining elements.

biosppy.utils.remainderAllocator(votes, k, reverse=True, check=False)[source]

Allocate k seats proportionally using the Remainder Method.

Also known as Hare-Niemeyer Method. Uses the Hare quota.

Parameters:

  • votes (list) – Number of votes for each class/party/cardinal.

  • k (int) – Total number o seats to allocate.

  • reverse (bool, optional) – If True, allocates remaining seats largest quota first.

  • check (bool, optional) – If True, limits the number of seats to the total number of votes.

Returns:

seats (list) – Number of seats for each class/party/cardinal.

biosppy.utils.walktree(top=None, spec=None)[source]

Iterator to recursively descend a directory and return all files matching the spec.

Parameters:

  • top (str, optional) – Starting directory; if None, defaults to the current working directoty.

  • spec (str, optional) – Regular expression to match the desired files; if None, matches all files; typical patterns: * r’.txt$’ - matches files with ‘.txt’ extension; * r’^File_’ - matches files starting with ‘File_’ * r’^File_.+.txt$’ - matches files starting with ‘File_’ and ending with the ‘.txt’ extension.

Yields:

fpath (str) – Absolute file path.

Notes

  • Partial matches are also selected.

See also