nnsa.decompositions package

Submodules

nnsa.decompositions.fourier module

Functions:

fftdeconvolve(x, h[, eps, axis])

Deconvolution by naive division in frequency domain.

nnsa.decompositions.fourier.fftdeconvolve(x, h, eps=1e-08, axis=-1)

Deconvolution by naive division in frequency domain.

Parameters:

• x (np.ndarray) – array to deconvolve.

• h (np.ndarray) – impulse response of deconvolution. Should have the same shape as x.

• eps (float) – threshold for the Fourier coefficients H to prevent division by small number.

• axis (int) – axis along which to devoncolve.

Returns:

y (np.ndarray) – resulting array with same shape as x.

nnsa.decompositions.side_obsp module

This module implements the SIgnal DEcomposition based on Oblique Subspace Projections (SIDE-ObSP).

This code was ported from Alexander Caicedo’s Matlab code by Tim Hermans.

References

A. Caicedo, C. Varon, B. Hunyadi, M. Papademetriou, I. Tachtsidis, and S. V. Huffel, “Decomposition of Near-Infrared Spectroscopy Signals Using Oblique Subspace Projections: Applications in Brain Hemodynamic Monitoring,” Frontiers in Physiology, vol. 7, Nov. 2016, doi: 10.3389/fphys.2016.00515.

Classes:

SideObsp([order, regularizer, gammas])

Class implementing SIgnal DEcomposition based on Oblique Subspace Projections.

Functions:

create_block_hankel(X, p)

Create a block Hankel expansion for signals in X with order p.

class nnsa.decompositions.side_obsp.SideObsp(order=None, regularizer='smooth', gammas=None)

Bases: object

Class implementing SIgnal DEcomposition based on Oblique Subspace Projections.

Parameters:

• order (int, optional) – order of the moving average model (number of taps). This is parameter p in Eq. 12. The order is equal for all inputs. This parameter can be set manually, or found automatically using cross-validation with the fit_hyper() method. Defaults to None.

• regularizer (str or None, optional) – regulizer to use for the linear model. See LinReg() for options. If None, no regularization is applied. Defaults to ‘smooth’.

• gammas (np.ndarray, optional) – regularization constant for each input. This is parameter gamma in Eq. 10. This parameter can be set manually, or found automatically using cross-validation with the fit_hyper() method. Not that the length of gammas must be equal to the number of input signals that will be used for the decomposition. Is not needed if regularizer is None. Defaults to None.

References

A. Caicedo, C. Varon, B. Hunyadi, M. Papademetriou, I. Tachtsidis, and S. V. Huffel, “Decomposition of Near-Infrared Spectroscopy Signals Using Oblique Subspace Projections: Applications in Brain Hemodynamic Monitoring,” Frontiers in Physiology, vol. 7, Nov. 2016, doi: 10.3389/fphys.2016.00515.

Examples

>>> n = 1024
>>> signal = generate_timeseries(n)
>>> noise = generate_timeseries(n)
>>> X = [signal, noise]
>>> y = signal + 2*noise + np.random.rand(n)
>>> y_hat = SideObsp(regularizer='smooth').fit_hyper(X, y, orders_all=[1, 2, 3, 4, 5]).fit_transform(X, y)
>>> y_signal, y_noise = y_hat[:, 0], y_hat[:, 1]
>>> y_denoise = y - y_noise

Methods:

fit(X, y[, k])	Fit the coefficient vector(s) h (impulse responses) for the kth input(s).
fit_hyper(X, y[, orders_all, gammas_all, ...])	Fit hyper parameters (order, gammas) using a grid search and k-fold cross validation.
fit_transform(X, y[, k])	Shortcut to do a fit and transform the data in one go.
transform(X[, k])	Decompose the output y into contributions for each input signal in X using fitted impulse responses.

Attributes:

gammas	Return the regularization constant for each input.
h	Return the impulse responses for each input (the impulses are flipped).
order	Return the model order.

fit(X, y, k=None)

Fit the coefficient vector(s) h (impulse responses) for the kth input(s).

Parameters:

• X (list or np.ndarray) – regressor matrix with shape (n_samples, n_inputs). Can also be a list with n_inputs arrays of length n_samples.

• y (list or np.ndarray) – the signal to decompose. Must be a list or 1D array with length n_samples.

• k (int or list, optional) – index specifying for which signals in X to to find the impulse responses that can be used to estimate the linear contribution of that signal to the output. If None, the impulse responses are computed for each input. Defaults to None.

Returns:

self – the object itself, but with fitted coefficients.

fit_hyper(X, y, orders_all=None, gammas_all=None, k_folds=10, verbose=2)

Fit hyper parameters (order, gammas) using a grid search and k-fold cross validation.

Parameters:

• X – see self.fit().

• y – see self.fit().

• orders_all (list or np.ndarray, optional) – list or 1D array with orders to try. The order is parameter p in Eq. 12. If None, a list with default values is used if self.order is None, otherwise the order will be kept fixed to the current value. Defaults to None.

• gammas_all (list or np.ndarray, optional) – list or 1D array with regularization constants to try. The regularization constant is parameter gamma (lower-case) in Eq. 10. If None, a list with default values is used if self.gammas is None, otherwise gammas will be kept fixed to the current value(s). Defaults to None.

• k_folds (int, optional) – the number of folds for k-fold cross-validation. Defaults to 10.

• verbose (int) – verbosity level. If 1, shows a progress bar. If 2, also prints the results.

Returns:

self – the object itself, but with fitted hyper parameters.

fit_transform(X, y, k=None)

Shortcut to do a fit and transform the data in one go.

property gammas

Return the regularization constant for each input.

property h

Return the impulse responses for each input (the impulses are flipped).

Returns:

(np.ndarray) – array with shape (order, num_inputs).

property order

Return the model order.

transform(X, k=None)

Decompose the output y into contributions for each input signal in X using fitted impulse responses.

This function can only be called after the model has been fit. It will raise an error otherwise.

Parameters:

• X – see self.fit().

• k – see self.fit().

Returns:

y_hat (np.ndarray) – the estimated linear contribution of each requested input regressor on the output y. Has shape (n_samples, len(k)).

nnsa.decompositions.side_obsp.create_block_hankel(X, p)

Create a block Hankel expansion for signals in X with order p.

Parameters:

• X (np.ndarray) – array containing multiple signals with shape (n_samples, n_signals).

• p (int) – truncation order (number of columns of the Hankel matrix after which to truncate).

Returns:

A (np.ndarray) – array containing the concatenated block Hankel matrices of each signal in X (Eq. 13). Has shape (n_samples - p + 1, n_signals * p).

Module contents

Code related to signal decomposition.

Classes:

SideObsp([order, regularizer, gammas])

Class implementing SIgnal DEcomposition based on Oblique Subspace Projections.

Functions:

create_block_hankel(X, p)	Create a block Hankel expansion for signals in X with order p.
fftdeconvolve(x, h[, eps, axis])	Deconvolution by naive division in frequency domain.

class nnsa.decompositions.SideObsp(order=None, regularizer='smooth', gammas=None)

Bases: object

Class implementing SIgnal DEcomposition based on Oblique Subspace Projections.

Parameters:

• order (int, optional) – order of the moving average model (number of taps). This is parameter p in Eq. 12. The order is equal for all inputs. This parameter can be set manually, or found automatically using cross-validation with the fit_hyper() method. Defaults to None.

• regularizer (str or None, optional) – regulizer to use for the linear model. See LinReg() for options. If None, no regularization is applied. Defaults to ‘smooth’.

• gammas (np.ndarray, optional) – regularization constant for each input. This is parameter gamma in Eq. 10. This parameter can be set manually, or found automatically using cross-validation with the fit_hyper() method. Not that the length of gammas must be equal to the number of input signals that will be used for the decomposition. Is not needed if regularizer is None. Defaults to None.

References

A. Caicedo, C. Varon, B. Hunyadi, M. Papademetriou, I. Tachtsidis, and S. V. Huffel, “Decomposition of Near-Infrared Spectroscopy Signals Using Oblique Subspace Projections: Applications in Brain Hemodynamic Monitoring,” Frontiers in Physiology, vol. 7, Nov. 2016, doi: 10.3389/fphys.2016.00515.

Examples

>>> n = 1024
>>> signal = generate_timeseries(n)
>>> noise = generate_timeseries(n)
>>> X = [signal, noise]
>>> y = signal + 2*noise + np.random.rand(n)
>>> y_hat = SideObsp(regularizer='smooth').fit_hyper(X, y, orders_all=[1, 2, 3, 4, 5]).fit_transform(X, y)
>>> y_signal, y_noise = y_hat[:, 0], y_hat[:, 1]
>>> y_denoise = y - y_noise

Methods:

fit(X, y[, k])	Fit the coefficient vector(s) h (impulse responses) for the kth input(s).
fit_hyper(X, y[, orders_all, gammas_all, ...])	Fit hyper parameters (order, gammas) using a grid search and k-fold cross validation.
fit_transform(X, y[, k])	Shortcut to do a fit and transform the data in one go.
transform(X[, k])	Decompose the output y into contributions for each input signal in X using fitted impulse responses.

Attributes:

gammas	Return the regularization constant for each input.
h	Return the impulse responses for each input (the impulses are flipped).
order	Return the model order.

fit(X, y, k=None)

Fit the coefficient vector(s) h (impulse responses) for the kth input(s).

Parameters:

• X (list or np.ndarray) – regressor matrix with shape (n_samples, n_inputs). Can also be a list with n_inputs arrays of length n_samples.

• y (list or np.ndarray) – the signal to decompose. Must be a list or 1D array with length n_samples.

• k (int or list, optional) – index specifying for which signals in X to to find the impulse responses that can be used to estimate the linear contribution of that signal to the output. If None, the impulse responses are computed for each input. Defaults to None.

Returns:

self – the object itself, but with fitted coefficients.

fit_hyper(X, y, orders_all=None, gammas_all=None, k_folds=10, verbose=2)

Fit hyper parameters (order, gammas) using a grid search and k-fold cross validation.

Parameters:

• X – see self.fit().

• y – see self.fit().

• orders_all (list or np.ndarray, optional) – list or 1D array with orders to try. The order is parameter p in Eq. 12. If None, a list with default values is used if self.order is None, otherwise the order will be kept fixed to the current value. Defaults to None.

• gammas_all (list or np.ndarray, optional) – list or 1D array with regularization constants to try. The regularization constant is parameter gamma (lower-case) in Eq. 10. If None, a list with default values is used if self.gammas is None, otherwise gammas will be kept fixed to the current value(s). Defaults to None.

• k_folds (int, optional) – the number of folds for k-fold cross-validation. Defaults to 10.

• verbose (int) – verbosity level. If 1, shows a progress bar. If 2, also prints the results.

Returns:

self – the object itself, but with fitted hyper parameters.

fit_transform(X, y, k=None)

Shortcut to do a fit and transform the data in one go.

property gammas

Return the regularization constant for each input.

property h

Return the impulse responses for each input (the impulses are flipped).

Returns:

(np.ndarray) – array with shape (order, num_inputs).

property order

Return the model order.

transform(X, k=None)

Decompose the output y into contributions for each input signal in X using fitted impulse responses.

This function can only be called after the model has been fit. It will raise an error otherwise.

Parameters:

• X – see self.fit().

• k – see self.fit().

Returns:

y_hat (np.ndarray) – the estimated linear contribution of each requested input regressor on the output y. Has shape (n_samples, len(k)).

nnsa.decompositions.create_block_hankel(X, p)

Create a block Hankel expansion for signals in X with order p.

Parameters:

• X (np.ndarray) – array containing multiple signals with shape (n_samples, n_signals).

• p (int) – truncation order (number of columns of the Hankel matrix after which to truncate).

Returns:

A (np.ndarray) – array containing the concatenated block Hankel matrices of each signal in X (Eq. 13). Has shape (n_samples - p + 1, n_signals * p).

nnsa.decompositions.fftdeconvolve(x, h, eps=1e-08, axis=-1)

Deconvolution by naive division in frequency domain.

Parameters:

• x (np.ndarray) – array to deconvolve.

• h (np.ndarray) – impulse response of deconvolution. Should have the same shape as x.

• eps (float) – threshold for the Fourier coefficients H to prevent division by small number.

• axis (int) – axis along which to devoncolve.

Returns:

y (np.ndarray) – resulting array with same shape as x.