Documentation of eeglib.eeg module¶
This module define the basic data structure that are used in this library
- class eeglib.eeg.EEG(windowSize, sampleRate, channelNumber, names=None)¶
Bases:
object
This class apply sginal analysis functions over the data stored in its attribute window.
- Attributes
- windowSize: int
The maximun samples the window will store.
- sampleRate: int
The number of samples per second
- channelNumber: int
The number of channels of samples the window will handle.
- window: SampleWindow
It stores the data.
Methods
CCC
([channels, allPermutations])Computes the Cross Correlation Coeficient between the data in c1 and the data in c2.
DFA
([i])Applies Detrended Fluctuation Analysis algorithm to the given data.
DFT
([i, windowFunction, output, …])Returns the Discrete Fourier Transform of the data at a given index of the window.
DTW
([channels, allPermutations, normalize, …])Computes the Dynamic Time Warping algortihm between the data of the given channels.
HFD
([i, kMax])Returns the Higuchi Fractal Dimension at the given index of the window.
LZC
([i])Returns the Lempel-Ziv Complexity at the given channel/s.
PFD
([i])Returns the Petrosian Fractal Dimension at the given index of the window.
PSD
([i, windowFunction, nperseg, retFrequencies])Returns the Power Spectral Density of the data at a given index of the window using the Welch method.
bandPower
([i, bands, spectrumFrom, …])Returns the power of each band at the given index.
Returns the engagament level, which is calculated with this formula: beta/(alpha+theta), where alpha, beta and theta are the average of the average band values between al the channels.
getBoundsForBand
(bandBounds)Returns the bounds of each band depending of the sample rate and the window size.
getChannel
([i])Returns the raw data stored at the given index of the windows.
getSignalAtBands
([i, bands])Rebuilds the signal from a component i but only in the specified frequency bands.
hjorthActivity
([i])Returns the Hjorth Activity at the given channel
hjorthComplexity
([i])Returns the Hjorth Complexity at the given channel
hjorthMobility
([i])Returns the Hjorth Mobility at the given channel
sampEn
([i])Returns Multiscale Sample Entropy at the given channel/s.
set
(samples[, columnMode])Sets multiple samples at a time into the window.
synchronizationLikelihood
([channels, …])Returns the Synchronization Likelihood value applied over the i1 and i2 channels by calling
synchronizationLikelihood()
.- CCC(channels=None, allPermutations=False)¶
Computes the Cross Correlation Coeficient between the data in c1 and the data in c2.
- Parameters
- channels: Variable type, optional
In order to understand how this parameter works go to the doc of
eeglib.eeg.EEG._applyFunctionTo2C()
- allPermutations: bool, optional
In order to understand how this parameter works go to the doc of
eeglib.eeg.EEG._applyFunctionTo2C()
- Returns
- float or dict
If a tuple is passed the it returns the result of applying the function to the channels specified in the tuple. If another valid value is passed, the method returns a dictionary, being the key the two channels used and the value the result of applying the function to those channels.
- DFA(i=None, *args, **kargs)¶
Applies Detrended Fluctuation Analysis algorithm to the given data.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used
- fit_degree: int, optional
Degree of the polynomial used to model de local trends. Default: 1.
- min_window_size: int, optional
Size of the smallest window that will be used. Default: signalSize//2.
- fskip: float, optional
Fraction of the window that will be skiped in each iteration for each window size. Default: 1.
- Returns
- float or array
The resulting value. If more than one channe was selected the return object will be a 1D array containing the result of the procesing.
- DFT(i=None, windowFunction=None, output='complex', onlyPositiveFrequencies=False)¶
Returns the Discrete Fourier Transform of the data at a given index of the window.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used.
- windowFunction: str, tuple or numpy.ndarray, optional
This can be a string with the name of the function, a tuple with a str with the name of the funcion in the first position and the parameters of the funcion in the nexts or a numpy array with a size equals to the window size. In the first case an array with the size of windowSize will be created. The created array will be multiplied by the data in the window before FFT is used.
- output: str, optional
“complex”: default output of the FFT, x+yi
“magnitude”: computes the magnitude of the FFT, sqrt(x^2+y^2)
“phase”: computes the phase of the FFT, atan2(yi,x)
- Returns
- numpy.ndarray
An array with the result of the Fourier Transform. If more than one channel was selected the array will be of 2 Dimensions.
- DTW(channels=None, allPermutations=False, normalize=False, returnOnlyDistances=True, *args, **kargs)¶
Computes the Dynamic Time Warping algortihm between the data of the given channels. It uses the FastDTW implementation given by the library fastdtw.
- Parameters
- channels: Variable type, optional
In order to understand how this parameter works go to the doc of
eeglib.eeg.EEG._applyFunctionTo2C()
- allPermutations: bool, optional
In order to understand how this parameter works go to the doc of
eeglib.eeg.EEG._applyFunctionTo2C()
- normalize: bool optional
If True the result of the algorithm is divided by the window size. Default: True.
- returnOnlyDistances: bool, optional
If True, the result of the function will include only the distances after applying the DTW algorithm. If False it will return also the path. Default: True.
- radiusint, optional
size of neighborhood when expanding the path. A higher value will increase the accuracy of the calculation but also increase time and memory consumption. A radius equal to the size of x and y will yield an exact dynamic time warping calculation.
- distfunction or int, optional
The method for calculating the distance between x[i] and y[j]. If dist is an int of value p > 0, then the p-norm will be used. If dist is a function then dist(x[i], y[j]) will be used. If dist is None then abs(x[i] - y[j]) will be used.
- Returns
- tuple, float, dict of floats or dict of tuples
If a tuple is passed the it returns the result of applying the function to the channels specified in the tuple. If another valid value is passed, the method returns a dictionary, being the key the two channels used and the value the result of applying the function to those channels.
- HFD(i=None, kMax=None)¶
Returns the Higuchi Fractal Dimension at the given index of the window.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used.
- kmax: int, optional
By default it will be windowSize//2.
- Returns
- float or array
The resulting value. If more than one channe was selected the return object will be a 1D array containing the result of the procesing.
- LZC(i=None, *args, **kargs)¶
Returns the Lempel-Ziv Complexity at the given channel/s.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used
- theshold: numeric, optional
A number use to binarize the signal. The values of the signal above threshold will be converted to 1 and the rest to 0. By default, the median of the data.
- normalize: bool
If True the resulting value will be between 0 and 1, being 0 the minimal posible complexity of a sequence that has the same lenght of data and 1 the maximal posible complexity. By default, False.
- Returns
- float or array
The resulting value. If more than one channe was selected the return object will be a 1D array containing the result of the procesing.
- PFD(i=None)¶
Returns the Petrosian Fractal Dimension at the given index of the window.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used.
- Returns
- float or array
The resulting value. If more than one channe was selected the return object will be a 1D array containing the result of the procesing.
- PSD(i=None, windowFunction='hann', nperseg=None, retFrequencies=False)¶
Returns the Power Spectral Density of the data at a given index of the window using the Welch method.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used.
- windowFunction: str or tuple or array_like, optional
Desired window to use. If window is a string or tuple, it is passed to get_window to generate the window values, which are DFT-even by default. See get_window for a list of windows and required parameters. If window is array_like it will be used directly as the window and its length must be nperseg. Defaults to a Hann window.
- nperseg: int, optional
Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.
- retFrequencies: bool, optional
If True two arrays will be raturned for each channel, one with the frequencies and another with the spectral density of those frequencies.
- Returns
- numpy.ndarray
An array with the result of the Fourier Transform. If more than one channel was selected the array will be of 2 Dimensions.
- __init__(windowSize, sampleRate, channelNumber, names=None)¶
- Parameters
- windowSize: int
The maximun samples the window will store.
- sampleRate: int
The number of samples per second
- channelNumber: int
The number of channels of samples the window will handle.
- names: list of strings, optional
The optional names that can be used to refer to each channel.
- bandPower(i=None, bands={'alpha': (8, 12), 'beta': (12, 30), 'delta': (1, 4), 'theta': (4, 7)}, spectrumFrom='DFT', windowFunction='hann', nperseg=None, normalize=False)¶
Returns the power of each band at the given index.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used.
- bands: dict, optional
This parameter is used to indicate the bands that are going to be used. It is a dict with the name of each band as key and a tuple with the lower and upper bounds as value.
- spectrumFrom: str, optional
“DFT”: uses the spectrum from the DFT of the signal.
“PSD”: uses the spectrum from the PSD of the signal.
- windowFunction: str or tuple or array_like, optional
Desired window to use. If window is a string or tuple, it is passed to get_window to generate the window values, which are DFT-even by default. See get_window for a list of windows and required parameters. If window is array_like it will be used directly as the window and its length must be nperseg. Defaults to a Hann window.
- nperseg: int, optional
This parameter is only relevant when powerFrom is “PSD”, else it is ignored. Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.
- normalize: bool, optional
If True the each band power is divided by the total power of the spectrum. Default False.
- Returns
- dict or list of dict
The keys are the name of each band and the values are the mean of the magnitudes. If more than one channel was selected the return object will be a list containing the dict for each channel selected
- engagementLevel()¶
Returns the engagament level, which is calculated with this formula: beta/(alpha+theta), where alpha, beta and theta are the average of the average band values between al the channels.
- Returns
- float
The engagement level.
- getBoundsForBand(bandBounds)¶
Returns the bounds of each band depending of the sample rate and the window size.
- Parameters
- bandbounds: tuple
A tuple containig the lower and upper bounds of a frequency band.
- Returns
- tuple
A tuple containig the the new bounds of the given band.
- getChannel(i=None)¶
Returns the raw data stored at the given index of the windows.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be returned as a 2D ndarray.
slice: a slice selecting the range of channels that wll be returned as a 2D ndarray.
None: all the data returned as a 2D ndarray
- Returns
- list
The list of values of a specific channel.
- getSignalAtBands(i=None, bands={'alpha': (8, 12), 'beta': (12, 30), 'delta': (1, 4), 'theta': (4, 7)})¶
Rebuilds the signal from a component i but only in the specified frequency bands.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used.
- bands: dict, optional
This parameter is used to indicate the bands that are going to be used. It is a dict with the name of each band as key and a tuple with the lower and upper bounds as value.
- Returns
- dict of numpy.ndarray (1D or 2D)
The keys are the same keys the bands dictionary is using. The values are the signal filtered in every band at the given index of the window. If more than one channel is selected the return object will be a dict containing 2D arrays in which each row is a signal filtered at the corresponding channel.
- hjorthActivity(i=None)¶
Returns the Hjorth Activity at the given channel
- Parameters
- i: int or string, optional
Index or name of the channel.
- Returns
- float or array
The resulting value. If more than one channe was selected the return object will be a 1D array containing the result of the procesing.
- hjorthComplexity(i=None)¶
Returns the Hjorth Complexity at the given channel
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used.
- Returns
- float or array
The resulting value. If more than one channe was selected the return object will be a 1D array containing the result of the procesing.
- hjorthMobility(i=None)¶
Returns the Hjorth Mobility at the given channel
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used.
- Returns
- float or array
The resulting value. If more than one channe was selected the return object will be a 1D array containing the result of the procesing.
- sampEn(i=None, *args, **kargs)¶
Returns Multiscale Sample Entropy at the given channel/s.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be used.
slice: a slice selecting the range of channels that will be used.
None: all the channels will be used
- m: int, optional
Size of the embedded vectors. By default 2.
- l: int, optional
Lag beetwen elements of embedded vectors. By default 1.
- r: float, optional
Tolerance. By default fr*std(data)
- fr: float, optional
Fraction of std(data) used as tolerance. If r is passed, this parameter is ignored. By default, 0.2.
- Returns
- float or array
The resulting value. If more than one channe was selected the return object will be a 1D array containing the result of the procesing.
- set(samples, columnMode=False)¶
Sets multiple samples at a time into the window. The sample number must be the same as the window size.
- Parameters
- samples: array_like of 2 dimensions
Samples of data with a size equals to window.
- columnMode: boolean, optional
By default it is assummed that the shape of the data given is nSamples X nchannels. If the given data is the inverse, columnMode should be True.
- synchronizationLikelihood(channels=None, allPermutations=False, m=None, l=None, w1=None, w2=None, pRef=0.05, **kargs)¶
Returns the Synchronization Likelihood value applied over the i1 and i2 channels by calling
synchronizationLikelihood()
.- Parameters
- channels: Variable type, optional
In order to understand how this parameter works go to the doc of
eeglib.eeg.EEG._applyFunctionTo2C()
- allPermutations: bool, optional
In order to understand how this parameter works go to the doc of
eeglib.eeg.EEG._applyFunctionTo2C()
- m: int, optional
Numbers of elements of the embedded vectors.
- l: int, optional
Separation between elements of the embedded vectors.
- w1: int, optional
Theiler correction for autocorrelation effects
- w2: int, optional
A window that sharpens the time resolution of the Synchronization measure
- pRef: float, optional
The p Ref param of the synchronizationLikelihood. Default 0.05
- epsilonIterations: int,optional
Number of iterations used to determine the value of epsilon
- Returns
- float or dict
If a tuple is passed the it returns the result of applying the function to the channels specified in the tuple. If another valid value is passed, the method returns a dictionary, being the key the two channels used and the value the result of applying the function to those channels.
- class eeglib.eeg.SampleWindow(windowSize, channelNumber, names=None)¶
Bases:
object
This class is a data structure that stores the signal data and works like a sliding window.
- Attributes
- windowSize: int
The maximun samples the window will store.
- channelNumber: int
The number of channels of samples the window will handle.
- window: list of lists
It stores the data.
Methods
getChannel
([i])Returns an array containing the data of the the selected channel/s.
Returns a list of numeric indices from a combined type of indices.
getPairOfChannels
([channels, allPermutations])Applies a function that uses two signals by selecting the channels to use.
getPairsIndicesList
(i[, allPermutations])Returns a list of tuples of numeric indices from a combined type of indices.
set
(samples[, columnMode])Sets multiple samples at a time.
- __init__(windowSize, channelNumber, names=None)¶
Creates a SampleWindow wich stores the value of windowSize as the number of samples and the value of channelNumber as the number of channels.
- Parameters
- windowSize: int
The size of the sliding window.
- channelNumber: int
The number of channels recording simultaneously.
- names: list of strings, optional
The optional names that can be used to refer to each channel.
- getChannel(i=None)¶
Returns an array containing the data of the the selected channel/s.
- Parameters
- i: Variable type, optional
int: the index of the channel.
str: the name of the channel.
list of strings and integers: a list of channels that will be returned as a 2D ndarray.
slice: a slice selecting the range of channels that wll be returned as a 2D ndarray.
None: all the data returned as a 2D ndarray
- Returns
- numpy.ndarray
Can be a one or a two dimension matrix, depending of the parameters.
- getIndicesList(i)¶
Returns a list of numeric indices from a combined type of indices.
- getPairOfChannels(channels=None, allPermutations=False)¶
Applies a function that uses two signals by selecting the channels to use. It will apply the function to different channels depending on the parameters. Note: a single channel can be selected by using an int or a string if a name for the channel was specified.
- Parameters
- channels: Variable type, optional
tuple of lenght 2 containing channel indexes: applies the function to the two channels specified by the tuple.
list of tuples(same restrictions than the above): applies the function to every tuple in the list.
list of index: creates combinations of channels specifies in the list depending of the allPermutations parameter.
None: Are channels are used in the same way than in the list above. This is the default value.
- allPermutations: bool, optional
Only used when channels is a list of index or None. If True all permutations of the channels in every order are used; if False only combinations of different channels are used. Example: with the list [0, 2, 4] and allPermutations = True, the channels used will be (0,2), (0,4), (2,0), (2,4), (4,0), (4,2); meanwhile, with allPermutations = False, the channels used will be: (0,2), (0,4), (2,4). Default: False.
- Returns
- If a tuple is passed the it returns the result of applying the function
- to the channels specified in the tuple. If another valid value is
- passed, the method returns a dictionary, being the key the two channels
- used and the value the result of applying the function to those
- channels.
- getPairsIndicesList(i, allPermutations=False)¶
Returns a list of tuples of numeric indices from a combined type of indices.
- set(samples, columnMode=False)¶
Sets multiple samples at a time. The sample number must be the same as the window size.
- Parameters
- samples: array_like of 2 dimensions
Samples of data with a size equals to window.
- columnMode: boolean, optional
By default it is assummed that the shape of the data given is nSamples X nchannels. If the given data is the inverse, columnMode should be True.