Analysis

This module provides basic time-domain and frequency-domain analysis tools tailored for balance data. This comprises biomechanical calculations as well as signal processing methods.

class balancepy.data_class.sr_data(samplingrate_Hz=None, stimulus=None, response=None, frequency_selection='all', name=None, freq=None, stimulus_spectrum=None, response_spectrum=None, frf=None)

Bases: object

Class to hold stimulus and response data for balancepy models.

Use add_timedomain_data to populate all attributes from stimulus and response data.

Parameters:

  • samplingrate_Hz (int, optional) – Sampling rate in Hz.

  • stimulus (ndarray, optional) – Stimulus data in cycles (1D or 2D array).

  • response (ndarray, optional) – Response data in cycles (1D or 2D array).

  • frequency_selection (str or list, optional) – Method for frequency selection, e.g., ‘all’, ‘prts’, ‘double_prts’, or a list of indices.

  • name (str, optional) – Name of the data set.

Attributes

Name

Description

samplingrate_Hz

Sampling rate in Hz.

stimulus

Stimulus data in cycles (1D or 2D array).

response

Response data in cycles (1D or 2D array).

frequency_selection

Frequency selection method or indices.

name

Name of the data set.

time

Time vector corresponding to the stimulus and response.

freq

Frequencies corresponding to the spectra.

stimulus_spectrum

Spectrum of the stimulus.

response_spectrum

Spectrum of the response.

frf

Frequency response function.

stimulus_mean

Mean of the stimulus across cycles (property).

response_mean

Mean of the response across cycles (property).

stimulus_mean0

Mean of the stimulus, centered around 0 (property).

response_mean0

Mean of the response, centered around 0 (property).

gain

Magnitude of the frequency response function (property).

phase

Phase of the frequency response function (property).

coherence

Coherence between stimulus and response (property).

stimulus_spectrum_mean

Mean of the stimulus spectrum across cycles (property).

response_spectrum_mean

Mean of the response spectrum across cycles (property).

stimulus_spectrum_PSD

Power spectral density of the stimulus spectrum (property).

response_spectrum_PSD

Power spectral density of the response spectrum (property).
balancepy.frequency.coherence(yi, yo)

Calculate the coherence between two signals in the frequency domain.

Parameters:

  • yi (NDArray[np.number]) – Spectrum of multiple cycles of the stimulus.

  • yo (NDArray[np.number]) – Spectrum of multiple cycles of the response.

Returns:

cohNDArray[np.number]

Coherence between the two signals.

balancepy.frequency.frf(yi, yo)

Calculate the frequency response function (FRF).

Parameters:

  • yi (array_like) – Complex stimulus spectrum; can be multiple cycles.

  • yo (array_like) – Complex response spectrum; can be multiple cycles.

Returns:

frfarray_like

Complex frequency response function (FRF).

balancepy.frequency.phase(frf, f)

Calculate the phase of the frequency response function (FRF).

Function performs additional phase unwrapping.

Parameters:

  • frf (array_like) – Complex frequency response function (FRF).

  • f (array_like) – Frequencies corresponding to the FRF.

Returns:

phaarray_like

Phase of the frequency response function (FRF) in degrees.

balancepy.frequency.spectrum(data, samplingrate_Hz)

Calculate scaled amplitude and power spectra of a time domain signal.

Amplitude spectrum is scaled such that the amplitude of a sine input is given by abs(Sx) Power spectrum Sxx is scaled such that sum(Sxx*df) = mean(data^2), where df is the frequency spacing.

Parameters:

  • data (array_like) – time domain signal, can be 1D or 2D.

  • samplingrate_Hz (float) – Sampling rate in Hz

Returns:

Sxarray_like

Scaled amplitude spectrum. 1D array for 1D input, 2D array for 2D input.

Sxxarray_like

Scaled power spectrum. 1D array for 1D input, 2D array for 2D input.

freqarray_like

Frequencies in Hz.

balancepy.timeseries.cut_to_cycles(data, cycle_start_samples=0, cycle_length_samples=1800, discard_cycles_index=[])

Cuts the data into cycles based on the provided cycle length, number of cycles, and a given start sample.

Parameters:

  • data (NDArray) – 1D data array to be cut into cycles

  • cycle_length_samples (int) – Length of cycles in samples

  • cycle_start_sample (int, optional) – Index of first sample of the first cycle

  • discard_cycles_list (NDArray[int], optional) – List of cycles to discard starting at 0 for first cycle

Returns:

2D array with cycles in columns

Return type:

NDArray

balancepy.timeseries.resample(time_s, data, sampling_rate, end_time_seconds=0)

resamples to fixed sample rate

Parameters:

  • time_s (np.ndarray) – 1D timestamps of original recording in seconds

  • data (np.ndarray) – 1D or 2D data array to be resampled

  • sr (int) – sampling rate in samples/second

  • end_time_seconds (float, optional) – optional end time of resampled data in seconds. Defaults to 0.

Returns:

1D or 2D with resampled data input

Return type:

NDArray

balancepy.timeseries.time_domain_analysis(xi, xo, samplingrate, bootstrap_samples=0)

analyse time domain input/output data.

Parameters:

  • xi (NDArray) – stimulus data

  • xo (NDArray) – response data

  • samplingrate (int) – sampling rate in Hz

Return type:

ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]