sigpyproc.core.stats

Statistical functions for computing moments of data.

This module contains functions for computing statistical moments of data.

Classes

ChannelStats	A class to compute the central moments of filterbank data in one pass.
ZScoreResult	Container for Z-score calculation results.

Functions

downsample_1d	Downsample a 1D array by reduction factor using a specified method.
downsample_2d	Downsample a 2D array by averaging over bins in both dimensions.
downsample_2d_flat	Downsample a flattened 2D array by averaging over bins in both dimensions.
estimate_loc	Estimate the location (central tendency) of an array.
estimate_scale	Estimate the scale (variability) or standard deviation of an array.
estimate_zscore	Calculate robust Z-scores of an array.
running_filter	Calculate the running filter of an array.
running_filter_fast	Calculate an approximate running filter of an array.

class sigpyproc.core.stats.ChannelStats(nchans, nsamps)

Bases: object

A class to compute the central moments of filterbank data in one pass.

Parameters:

nchansint

Number of channels in the data.

nsampsint

Number of samples in the data.

Attributes:

nchans

Get the number of channels.

nsamps

Get the number of samples.

moments

Get the central moments of the data.

maxima

Get the maximum value of each channel.

minima

Get the minimum value of each channel.

mean

Get the mean of each channel.

var

Get the variance of each channel.

std

Get the standard deviation of each channel.

skew

Get the skewness of each channel.

kurtosis

Get the kurtosis of each channel.

Methods

push_data(array, start_index[, mode])

Update the central moments of the data with new samples.

References

[1]

Wikipedia, “Algorithms for calculating variance”, https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Online_algorithm

[2]

John D. Cook, “Skewness and kurtosis formulas for normal distributions”, https://www.johndcook.com/blog/skewness_kurtosis/

[3]

Pebay, Philippe P., “One-Pass covariances and Statistical Moments”, https://doi.org/10.2172/1028931

property nchans

Get the number of channels.

Returns:

int

The number of channels.

property nsamps

Get the number of samples.

Returns:

int

The number of samples.

property moments

Get the central moments of the data.

Returns:

ndarray

The central moments of the data.

property maxima

Get the maximum value of each channel.

Returns:

ndarray

The maximum value of each channel.

property minima

Get the minimum value of each channel.

Returns:

ndarray

The minimum value of each channel.

property mean

Get the mean of each channel.

Returns:

ndarray

The mean of each channel.

property var

Get the variance of each channel.

Returns:

ndarray

The variance of each channel.

property std

Get the standard deviation of each channel.

Returns:

ndarray

The standard deviation of each channel.

property skew

Get the skewness of each channel.

Returns:

ndarray

The skewness of each channel.

property kurtosis

Get the kurtosis of each channel.

Returns:

ndarray

The kurtosis of each channel.

push_data(array, start_index, mode='basic')

Update the central moments of the data with new samples.

Parameters:

arrayndarray

The input array to update the moments with.

start_indexint

The starting time (sample) index of the data.

mode{“basic”, “full”}, optional

The mode to use for computing the moments, by default “basic”.

• “basic” : Compute the moments upto 2nd order (variance).

• “full” : Compute the moments upto 4th order (kurtosis).

class sigpyproc.core.stats.ZScoreResult(*, data, loc, scale)

Bases: object

Container for Z-score calculation results.

Parameters:

datandarray

Robust Z-scores of the input array (normalized data).

locfloat

Estimated location (central tendency) used for the Z-score calculation.

scalefloat | ndarray

Estimated scale (variability) used for the Z-score calculation. Can be a scalar or an array matching the shape of data.

Attributes:

data

loc

scale

data

loc

scale

sigpyproc.core.stats.downsample_1d(array, factor, method='mean')

Downsample a 1D array by reduction factor using a specified method.

Remainder samples are dropped.

Parameters:

arrayndarray

The input 1D array to downsample. Supports 1D numeric dtype.

factorint

The downsampling factor.

method{“mean”, “median”}, optional

The method to use for downsampling, by default “mean”.

Returns:

ndarray

The downsampled array.

Raises:

ValueError

If the method is not supported.

sigpyproc.core.stats.downsample_2d(array, factors, method='mean')

Downsample a 2D array by averaging over bins in both dimensions.

Parameters:

arraynp.ndarray

Input 2D array to be downsampled.

factorstuple[int, int]

Downsampling factors (factor1, factor2) for each dimension. Must be positive integers.

method{“mean”, “median”}, optional

Downsampling method, by default “mean”.

Returns:

np.ndarray

Downsampled array with same layout as input.

sigpyproc.core.stats.downsample_2d_flat(array, factor1, factor2, dim1, dim2, method='mean')

Downsample a flattened 2D array by averaging over bins in both dimensions.

Parameters:

arraynp.ndarray

Input flattened 2D array to be downsampled.

factor1int

Downsampling factor for the first dimension. Must be a positive integer.

factor2int

Downsampling factor for the second dimension. Must be a positive integer.

dim1int

Number of bins in the first dimension.

dim2int

Number of bins in the second dimension.

method{“mean”, “median”}, optional

Downsampling method, by default “mean”.

Returns:

np.ndarray

Downsampled flattened 2D array

Notes

dim2 must ve the fastest varying dimension.

sigpyproc.core.stats.estimate_loc(data, method='median', axis=None, *, keepdims=False)

Estimate the location (central tendency) of an array.

Parameters:

dataArrayLike

Input array or object that can be converted to an array.

method{“median”, “mean”}, optional

The method to use for estimating the location, by default “median”.

axisint | tuple[int, …] | None, optional

Axis or axes along which to compute the location, by default None.

keepdimsbool, optional

If True, the reduced axis is kept in the result, by default True.

Returns:

float | ndarray

The estimated location of the array.

Raises:

ValueError

If the array is empty or if the method is not supported.

sigpyproc.core.stats.estimate_scale(data, method='mad', axis=None, *, keepdims=False)

Estimate the scale (variability) or standard deviation of an array.

Parameters:

dataArrayLike

Input array or object that can be converted to an array.

method{“std”, “iqr”, “mad”, “doublemad”, “diffcov”, “biweight”, “qn”, “sn”, “gapper”}, optional

The method to use for estimating the scale, by default “mad”.

• std : Standard Deviation.

• iqr : Normalized Inter-quartile Range.

• mad : Median Absolute Deviation.

• doublemad : Double MAD.

• diffcov : Difference Covariance

• biweight : Biweight Midvariance

• qn : Normalized Qn scale

• sn : Normalized Sn scale

• gapper : Gapper Estimator

axisint | tuple[int, …] | None, optional

Axis or axes along which to compute the scale, by default None.

keepdimsbool, optional

If True, the reduced axis is kept in the result, by default True.

Returns:

float64 | NDArray[float64]

The estimated scale of the array. If the method is “doublemad”, the output is an array of the same shape as the input array.

Raises:

ValueError

If the array is empty or if the method is not supported.

References

[1]

Wikipedia, “Robust measures of scale”, https://en.wikipedia.org/wiki/Robust_measures_of_scale

sigpyproc.core.stats.estimate_zscore(data, loc_method='median', scale_method='mad', axis=0)

Calculate robust Z-scores of an array.

Parameters:

dataArrayLike

Input array or object that can be converted to an array.

loc_method{“median”, “mean”, “norm”}, optional

The method to use for estimating the location, by default “median”.

Use “norm” to set the location to 0.

scale_method{“std”, “iqr”, “mad”, “doublemad”, “diffcov”, “biweight”, “qn”, “sn”, “gapper”, “norm”}, optional

The method to use for estimating the scale, by default “mad”.

Use “norm” to set the scale to 1.

axisint | None, optional

Axis along which to compute the Z-scores, by default 0.

Returns:

ZScoreResult

A container with the Z-scores, estimated location, and scale.

Raises:

ValueError

If the loc_method or scale_method is not supported.

See also

estimate_loc, estimate_scale

scipy.stats.zscore

sigpyproc.core.stats.running_filter(array, window, method='mean')

Calculate the running filter of an array.

Applies a sliding window filter to the input array using the specified method. Window edges are handled by reflecting about the edges of the input array.

Parameters:

arrayndarray

The input array to filter.

windowint

The size of the sliding window.

method{“mean”, “median”}, optional

The filtering method to use, by default “mean”.

Returns:

ndarray

The filtered array with the same shape as the input array.

Raises:

ValueError

If the method is not supported.

sigpyproc.core.stats.running_filter_fast(array, window, method='mean', min_points=101)

Calculate an approximate running filter of an array.

Downsamples the input array, apply the running filter, and then interpolate back to the original size. This is faster than the regular running filter for large arrays.

Parameters:

arrayndarray

The input array to filter.

windowint

The size of the sliding window.

method{“mean”, “median”}, optional

The filtering method to use, by default “mean”.

min_pointsint, optional

The minimum number of nsamples for the downsampled array, by default 101. Lower values will result in faster processing but less accurate results.

Returns:

ndarray

The filtered array with the same shape as the input array.