gridcells.analysis.signal - signal analysis

The can be e.g. filtering, slicing, correlation analysis, up/down-sampling, etc.

acorr(sig[, max_lag, norm, mode])	Compute an autocorrelation function of a real signal.
corr(a, b[, mode, lag_start, lag_end])	An enhanced correlation function of two real signals, based on a custom C++ code.
ExtremumTypes	Specifies types of extrema.
local_extrema(sig)	Find all local extrema using the derivative approach.
local_maxima(sig)	Find all local maxima using the derivative approach
local_minima(sig)	Find all local minima using the derivative approach
LocalExtrema(extrema, types)	A class representing local extrema for a particular object.

gridcells.analysis.signal.acorr(sig, max_lag=None, norm=False, mode='onesided')

Compute an autocorrelation function of a real signal.

Parameters:

sig : numpy.ndarray

The signal, 1D vector, to compute an autocorrelation of.

max_lag : int, optional

Maximal number of lags. If mode == ‘onesided’, the range of lags will be [0, max_lag], i.e. the size of the output will be (max_lag+1). If mode == ‘twosided’, the lags will be in the range [-max_lag, max_lag], and so the size of the output will be 2*max_lag + 1.

If max_lag is None, then max_lag will be set to len(sig)-1

norm : bool, optional

Whether to normalize the auto correlation result, so that res(0) = 1

mode : string, optional

onesided or twosided. See description of max_lag

output : numpy.ndarray

A 1D array, size depends on max_lag and mode parameters.

Notes

If the normalisation constant is zero (i.e. the input array is zero), this function will return a zero array.

gridcells.analysis.signal.corr(a, b, mode='onesided', lag_start=None, lag_end=None)

An enhanced correlation function of two real signals, based on a custom C++ code.

This function uses dot product instead of FFT to compute a correlation function with range restricted lags.

Thus, for a long-range of lags and big arrays it can be slower than the numpy.correlate (which uses fft-based convolution). However, for arrays in which the number of lags << max(a.size, b.size) the computation time might be much shorter than using convolution to calculate the full correlation function and taking a slice of it.

Parameters:

a, b : ndarray

One dimensional numpy arrays (in the current implementation, they will be converted to dtype=double if not already of that type.

mode : str, optional

A string indicating the size of the output:

onesided : range of lags is [0, b.size - 1]

twosided : range of lags is [-(a.size - 1), b.size - 1]

range : range of lags is [-lag_start, lag_end]

lag_start, lag_end : int, optional

Initial and final lag value. Only used when mode == ‘range’

output : numpy.ndarray with shape (1, ) and dtype.float

A 1D array of size depending on mode

Note

This function always returns a numpy array with dtype=float.

See also

acorr()

gridcells.analysis.signal.local_extrema(sig)

Find all local extrema using the derivative approach.

Parameters:

sig : numpy.ndarray

A 1D numpy array

Returns:

extrema : LocalExtrema

An object containing the local extrema of the signal sig.

See also

local_minima

Finds local minima.

local_maxima

Finds local maxima.

Notes

This method is not suitable to find local extrema of functions where the extremum is flat, i.e. as in square pulses.

gridcells.analysis.signal.local_minima(sig)

Find all local minima using the derivative approach

Parameters:

sig : numpy.ndarray

A 1D numpy array

Returns:

maxima : np.ndarray

An array of indices into sig of the local minima.

See also

local_extrema

Finds local extrema.

local_maxima

Finds local maxima.

gridcells.analysis.signal.local_maxima(sig)

Find all local maxima using the derivative approach

Parameters:

sig : numpy.ndarray

A 1D numpy array

Returns:

maxima : np.ndarray

An array of indices into sig of the local maxima.

See also

local_extrema

Finds local extrema.

local_minima

Finds local minima.

class gridcells.analysis.signal.ExtremumTypes

Bases: enum.IntEnum

Specifies types of extrema.

MAX = None

Local maximum.

MIN = None

Local minimum.

UNDEFINED = None

Undefined.

class gridcells.analysis.signal.LocalExtrema(extrema, types)

Bases: object

A class representing local extrema for a particular object.

This is only a helper class. Users should not instantiate this class directly

Note

For now only 1D extrema are supported.

Parameters:

extrema : 1D numpy array

Positions of the extrema in a signal. The user must track the source.

types : 1D numpy array

Types of the extrema held in this object. Contains values from ExtremumTypes.

get_type(extremum_type)

Get all the local extrema that are of type extremum_type.

Parameters:

extremum_type : ExtremumTypes

The type of the extremum to retrieve.

Returns:

extrema : iterable

An iterable that will contain the extrema with the specified type. If no extremum of the requested type is present, returns an empty array.