NEUREQUA.quality_module

Functions

ensure_dir(→ None)

Create the directory if it does not exist

load_raw_data(path, dtype, length, pattern2exclude[, ...])

Load data from the raw files (e.g., .ncs for Neuralynx)

splitCharNum(string)

Separate a string containing characters and numbers in two objects

get_unique_unsorted(array)

Maintains the order of appearance in the original array

reorder_data(Regions, data)

When there is 3 tetrodes on the same shaft order will be x1, x10, x11, x12, x2, x3 ... x9 on the raw file

find_nearest(array, value)

Find the index where there is the nearest values in an array from the one we want

random_time(data, sampling_rate, length)

Select randomly length minutes of signal from your entire recoding

p_welch(data, chRegions, sub, sess, sr, sr_down, ...)

Compute the power spectrum of your signal in order to identify frequencies present in your signal

plot_all_chan(f, nCh, chRegs, psd, bsnm, session, ...)

This function will plot the power spectrum of all micro-channels on the same plot

plot_tetrode(metrics, chRegions)

Function used to plot the metrics value of each tetrodes grouped by colors

plot_noise(data, sr, chRegions, path[, save, limit, ...])

This function will plot the raw signal filtered between 300 and 300 Hz for 1 second randomly choosed in the 5 minutes window

plot_raw(data, sr, num_channel, path[, save])

In entry take the 5 minutes of signal that were randomly choosed before

tblprep(path, electrodes, sub, sess)

Here we prep the excel file where all metrics values will be stored

rms_signal_filtered(data, path, chRegions, sub, sess, ...)

Here we take the 5 minutes of signal that were randomly choosed before

plot_rms_filter(pathtbl, savingpath, sub, sess[, save])

This function is used to plot the Root-mean square value of each channels

correlation_coefficient(data, chRegions, path, ...[, save])

This function compute a correlation coefficient between one micro-wire and all the other micro-wires

variance_normalized(data, chRegions, path, pathtbl, ...)

Compute the variance of each channel normalized by the mean variance of all neighbouring channels on the same tetrode

deviation(data, chRegions, path, pathtbl, sub, sess, ...)

Compute the deviation (i.e. electrical drift)

variance(data, chRegions, path, pathtbl, sub, sess[, save])

Compute the variance of each channel to see if there is a lot of artefacts or not

signaltonoise(a, chRegions, path, pathtbl, sub, sess)

The signal-to-noise ratio of the input data.

kurtosis(data, chRegions, path, pathtbl, sub, sess[, save])

Kurtosis: An electrical activity may appear in one of the channels and be absent in the remaining ones.

hurst_component(data, chRegions, path, pathtbl, sub, sess)

Compute the Hurst component

Module Contents

NEUREQUA.quality_module.ensure_dir(path: str) → None[source]

Create the directory if it does not exist

Parameters:

path (string) – Path-like where you want to create folder

NEUREQUA.quality_module.load_raw_data(path, dtype, length, pattern2exclude, time='Random', analog=False, *args)[source]

Load data from the raw files (e.g., .ncs for Neuralynx)

This function supports multiple file formats: - .ncs for Neuralynx acquisition system - .nsX for Blaclrock acquisition system - .med for Darkhorseneuro acquisition system - .edf

This function is based on MNE [1] and NEO [2] framework

Returns two objects :

  1. A raw-object from MNE (see https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw for documentation)

  2. An array containing raw values of the signal you want to analyze

Parameters:

  • path (string) – A string containing the path where your data are stored

  • dtype (string) – For Neuralynx data : ‘ncs’ For Blackrock data : ‘nsX’ For Dark Horse Neuro data : ‘med’ edf is also supported : ‘edf’

  • length (int or 'all') – If you specify length with a int (e.g., 5) it will select randomly 5 minute of signal If you specify ‘all’ it will take the entire recording (can be slower, depends on your computational resources)

  • pattern2exclude (string) – Pattern that enables us to not take into account the macrocontacts (e.g., in Toulouse all macro contacts have the suffix _sub so the argument will be ‘_sub.ncs’)

  • time (string or tuple (Default='Random')) – By default take randomly portion of signal corresponding to length It can be a tuple (2,7) for example to take signal from 2 minutes to 7 minutes of the recording

  • analog (string (optional) (Default: False)) – Reference channel used in blackrock recording system if it exists

Returns:

  • raw_data (raw data in FIF format (see MNE)) – This object contains all informations about your data (channels name, sampling rate etc.)

  • data_sig (np array) – Array containing raw values of the signal you want to load Will have a shape of nCh x nSamples

References

[1] Gramfort A, Luessi M, Larson E, Engemann DA, Strohmeier D, Brodbeck C, Parkkonen L, Hämäläinen MS. MNE software for processing MEG and EEG data. Neuroimage. 2014 Feb 1;86:446-60. doi: 10.1016/j.neuroimage.2013.10.027. Epub 2013 Oct 24. PMID: 24161808; PMCID: PMC3930851.

[2] Garcia S., Guarino D., Jaillet F., Jennings T.R., Pröpper R., Rautenberg P.L., Rodgers C., Sobolev A.,Wachtler T., Yger P. and Davison A.P. (2014) Neo: an object model for handling electrophysiology data in multiple formats. Frontiers in Neuroinformatics 8:10: doi:10.3389/fninf.2014.00010

NEUREQUA.quality_module.splitCharNum(string)[source]

Separate a string containing characters and numbers in two objects (One with characters and one with numbers)

Parameters:

string (string) – String containing characters and numbers (e.g., ‘da1’)

Returns:

  • char (string) – string containing only the characters from the input (e.g., ‘da’)

  • number (string) – string containing only the numbers from the input (e.g., ‘1’)

NEUREQUA.quality_module.get_unique_unsorted(array)[source]

Maintains the order of appearance in the original array Does not sort by ascending order (figures) or alphabetic order (characters)

Parameters:

array (array of string) – Array of string containing the name of your channels (e.g. [‘da’,’db’])

Returns:

uniqueUnsorted – array of string containing

Return type:

string

NEUREQUA.quality_module.reorder_data(Regions, data)[source]

When there is 3 tetrodes on the same shaft order will be x1, x10, x11, x12, x2, x3 … x9 on the raw file We want to re-organize it so the order is x1, x2, x3 … x9, x10, x11, x12 Will return the array of regions name and data in the right order

Parameters:

  • Regions (array of string) – Array of strings containing all the name of the regions implanted with your channels

  • data (array) – Matrix containing raw values with shape nChannels x nSamples

Returns:

  • Regions_ok (array of string) – Array of strings containing the name in the right order (e.g., ‘x1’, ‘x2’, ‘x3’ … ‘x9’, ‘x10’, ‘x11’, ‘x12’)

  • data_ok (array) – Matrix with shape nChannels x nSamples but re-organize to match the order of channel labels

NEUREQUA.quality_module.find_nearest(array, value)[source]

Find the index where there is the nearest values in an array from the one we want

Parameters:

  • array (np.array) – array containing data (e.g., [2, 7, 12])

  • value (int) – The value we want to find the closest (e.g. 11)

Returns:

idx – Will return the index in array closest to value (e.g., 2)

Return type:

int

NEUREQUA.quality_module.random_time(data, sampling_rate, length)[source]

Select randomly length minutes of signal from your entire recoding

Parameters:

  • data (MNE-raw object) – The structure of a RAW mne object containing metadata

  • rate (sampling) – The sampling rate of your recording (e.g., 32768)

  • length (int) – Length in minute of the signal you want to analyze

Returns:

start_idx – Correspond to the first sample of the signal, the beginning of the recording you want to analyze

Return type:

int

NEUREQUA.quality_module.p_welch(data, chRegions, sub, sess, sr, sr_down, fr_low, fr_high, saveFolder, probe_type='Dixi')[source]

Compute the power spectrum of your signal in order to identify frequencies present in your signal Here we use the welch’s method to compute the power spectrum.

Parameters:

  • data (array) – Matrice containing data of all channels containing nSamples

  • chRegions (Numpy array) – Array containing the labels of all the electrodes in the recording

  • sub (string) – ID of the patient you are analyzing

  • sess (string) – Name of the session you are analyzing

  • sr (int) – Sampling rate of your recording (e.g., 32768)

  • sr_down (int) – Sampling rate downsampled, so the one you want (e.g., 8192 Hz)

  • fr_low (int) – The lowest frequency from which we compute the power spectrum

  • fr_high (int) – The highest frequency from which we compute the power spectrum

  • saveFolder (string) – Path where you want to save the output figure

  • probe_type (string (Default=Dixi)) – String containing the model of your electrodes, it can be either ‘Dixi’ or ‘Ad-tech’

Returns:

  • pxx_log (array) – Array containing power spectrum values for the channel of interest

  • f_plot (array) – Array containing the values of frequency associate with each power spectrum value (will be useful for the plot)

NEUREQUA.quality_module.plot_all_chan(f, nCh, chRegs, psd, bsnm, session, probe_type, saveFolder)[source]

This function will plot the power spectrum of all micro-channels on the same plot

Parameters:

  • f (array) – Array containing frequency values (it is the output of p_welch)

  • nCh (int) – Number of channels in your recording

  • chRegs (array of strings) – Array containing name of your channels

  • psd (array) – Array of power spectrum values for each value of f, it is the output of p_welch

  • session (string) – Name of the session you analyze, specify at the beginning of the jupyter notebook

  • probe_type (string) – String containing the model of micro-electrodes you have in your dataset (for now: Dixi or Ad-tech only)

  • saveFolder (string) – String containing the path of the folder where you want to save figure

Return type:

Matplotlib plot containing power spectrum of each channels and saved in the folder specified

NEUREQUA.quality_module.plot_tetrode(metrics, chRegions)[source]

Function used to plot the metrics value of each tetrodes grouped by colors

NEUREQUA.quality_module.plot_noise(data, sr, chRegions, path, save=1, limit='auto', fr_low=300, fr_high=3000)[source]

This function will plot the raw signal filtered between 300 and 300 Hz for 1 second randomly choosed in the 5 minutes window So we can have an idea of the level of noise during our recording

Parameters:

  • data (array) – Matrix with your data with shape nChannels x nSamples

  • sr (int) – sampling rate of the signal

  • chRegions (string) – Array of string containing name of each channels

  • path (string) – String containing the path where you want to save the figures

  • save (int, default = 1) – If you don’t want to save figure put save = 0

  • limit (string) – Default value is ‘auto’ so matplotlib handes the limit but otherwise it is the min and max of your data Could be useful to better see the level of noise in your recording

  • fr_low (int, default = 300) – The lowest frequency for your band pass filter

  • fr_high (int, default = 3000) – The highest frequency for your band pass filter

Return type:

Matplotlib plot saved in the specific folder if you want to

NEUREQUA.quality_module.plot_raw(data, sr, num_channel, path, save=1)[source]

In entry take the 5 minutes of signal that were randomly choosed before This function will plot the raw signal for 1 second randomly choosed in the 5 minutes window

Parameters:

  • data (array) – data from one particular channel

  • sr (int) – sampling rate of the signal

  • num_channel (int) – Number of the channel in your recording

  • path (string) – Path where you want to store your figure in output

  • save (Boolean) – Default = 1 else put save = 0

Return type:

Matplotlib plot with raw signal

NEUREQUA.quality_module.tblprep(path, electrodes, sub, sess)[source]

Here we prep the excel file where all metrics values will be stored You can either create a file for each session or patient by changing the name of path But you could also keep the same file and then store values to create a database.

Parameters:

  • path (string) – Path where you want to store the excel file containing the metrics or an existing file to store values

  • electrodes (array of string) – Array containing the name of your electrodes (automatically extracted from your recording)

  • sub (string) – Name of the subject analyzed

  • sess (string) – Name of the session analyzed

Outputs

It creates an excel file where metrics will be stored

NEUREQUA.quality_module.rms_signal_filtered(data, path, chRegions, sub, sess, fr_low, fr_high, sr, saveFolder, save=1)[source]

Here we take the 5 minutes of signal that were randomly choosed before This function will calculate the RMS (root mean square) for 1 second randomly choosed in the 5 minutes window

Parameters:

  • data (numpy.array) – 2-D Matrice containing all your data with shape nChannels x nSamples

  • path (string) – Path where is the excel file you created earlier

  • chRegions (array of string) – Name of the electrodes in your recordings

  • sub (string) – Name of the subject analyzed

  • sess (string) – Name of the session analyzed

  • fr_low (int) – Low frequency to filter the data (e.g., 300)

  • fr_high (int) – High frequency to filter the data (e.g., 3000)

  • sr (int) – Sampling rate of the signal of your recording system

  • saveFolder (string) – Path where you want to store the outputes figure

  • Outputs

  • ---------------------------

  • filtered (Figure with the values of RMS of your signal)

NEUREQUA.quality_module.plot_rms_filter(pathtbl, savingpath, sub, sess, save=1)[source]

This function is used to plot the Root-mean square value of each channels

NEUREQUA.quality_module.correlation_coefficient(data, chRegions, path, pathtbl, sub, sess, probe_type, save=1)[source]

This function compute a correlation coefficient between one micro-wire and all the other micro-wires from the same tetrode

see Tuyisenge, V., Trebaul, L., Bhattacharjee, M., Chanteloup-Forêt, B., Saubat-Guigui, C., Mîndruţă, I., Rheims, S., Maillard, L., Kahane, P., Taussig, D., & David, O. (2018). Automatic bad channel detection in intracranial electroencephalographic recordings using ensemble machine learning. Clinical Neurophysiology, 129(3), 548‑554. https://doi.org/10.1016/j.clinph.2017.12.013

Parameters:

  • data (array) – Matrix with your data with shape nChannels x nSamples

  • chRegions (Array) – Vector with the name of the micro-wires

  • path (string) – Path where you want to save the figure obtained

  • pathtbl (string) – Path where you store the excel file containing all values for the patient you analyze

  • sub (string) – String like ‘sub-XX’ with XX being the number of the subject in your database

  • sess (string) – String containing the name of the session you are analyzing (specified at the beginning of the jupyter notebook)

  • probe_type (string) – String containing the model of micro-electrodes you have in your dataset (for now: Dixi or Ad-tech only)

  • save (int (default=1)) – To save the figure, put save = 0 if you don’t want to save the figure

Returns:

  • Matplotlib plot with correlation coefficient for each channel

  • Values of the correlation coefficient saved in an excel fil to get a report of the analyzes

NEUREQUA.quality_module.variance_normalized(data, chRegions, path, pathtbl, sub, sess, probe_type, save=1)[source]

Compute the variance of each channel normalized by the mean variance of all neighbouring channels on the same tetrode If variance is high then it means that the channel is not recording the same activity than the ones around, so maybe it is broken or there is a problem with the plugging on your recording system

Parameters:

  • data (array) – Matrix with your data with shape nChannels x nSamples

  • chRegions (array of strings) – Vector with the name of your channels

  • path (string) – Path where you want to save output figure

  • pathtbl (string) – Path where the excel file of this patient is stored

  • sub (string) – String containing the number or the ID of the patient in your database

  • sess (string) – String containing the name of the session you are analyzing

  • probe_type (string) – String containing the model of micro-electrodes you have in your dataset (for now: Dixi or Ad-tech only)

save: int (Default=1)

To save figure or not (put = 0 to not save)

Returns:

  • Matplotlib plot with values of variance normalized

  • Values are also stored in the excel file

see Tuyisenge, V., Trebaul, L., Bhattacharjee, M., Chanteloup-Forêt, B., Saubat-Guigui, C., Mîndruţă, I., Rheims, S., Maillard, L., Kahane, P., Taussig, D., & David, O. (2018). Automatic bad channel detection in intracranial electroencephalographic recordings using ensemble machine learning. Clinical Neurophysiology, 129(3), 548‑554. https://doi.org/10.1016/j.clinph.2017.12.013

NEUREQUA.quality_module.deviation(data, chRegions, path, pathtbl, sub, sess, probe_type, save=1)[source]

Compute the deviation (i.e. electrical drift)

Parameters:

  • data (array) – Matrix with your data with shape nChannels x nSamples

  • chRegions (array of strings) – Vector with the name of your channels

  • path (string) – Path where you want to save the output’s figure

  • paththbl (string) – Path where to store values in excel

  • sub (string) – IDs of the patient

  • sess (string) – Name of the session

  • probe_type (string) – String containing the model of micro-electrodes you have in your dataset (for now: Dixi or Ad-tech only)

Return type:

Matplotlib plot and values in excel file

see Tuyisenge, V., Trebaul, L., Bhattacharjee, M., Chanteloup-Forêt, B., Saubat-Guigui, C., Mîndruţă, I., Rheims, S., Maillard, L., Kahane, P., Taussig, D., & David, O. (2018). Automatic bad channel detection in intracranial electroencephalographic recordings using ensemble machine learning. Clinical Neurophysiology, 129(3), 548‑554. https://doi.org/10.1016/j.clinph.2017.12.013

NEUREQUA.quality_module.variance(data, chRegions, path, pathtbl, sub, sess, save=1)[source]

Compute the variance of each channel to see if there is a lot of artefacts or not

Parameters:

  • data (array) – Matrix with your data with shape nChannels x nSamples

  • chRegions (array of strings) – Vector with the name of your channels

  • path (string) – Path where you want to save output figure

  • paththbl (string) – Path to the excel file where to store informations

  • sub (string) – IDs of the patient

  • sess (string) – Name of the session

  • save (int (Default=1)) – To save figure

Return type:

Matplotlib plot and value store in excel file

NEUREQUA.quality_module.signaltonoise(a, chRegions, path, pathtbl, sub, sess, save=1, axis=1, ddof=0)[source]

The signal-to-noise ratio of the input data.

Returns the signal-to-noise ratio of a, here defined as the mean divided by the standard deviation.

Parameters:

  • a (array_like) – An array_like object containing the sample data.

  • axis (int or None, optional) – If axis is equal to None, the array is first ravel’d. If axis is an integer, this is the axis over which to operate. Default is 0.

  • ddof (int, optional) – Degrees of freedom correction for standard deviation. Default is 0.

Returns:

s2n – The mean to standard deviation ratio(s) along axis, or 0 where the standard deviation is 0.

Return type:

ndarray

NEUREQUA.quality_module.kurtosis(data, chRegions, path, pathtbl, sub, sess, save=1)[source]

Kurtosis: An electrical activity may appear in one of the channels and be absent in the remaining ones. Such events can be detected by computing the kurtosis in all channels. Given that the kurtosis indicates the presence of outliers in datasets, the highest value reveals which channel shows a particular event (Mognon et al., 2011) (from Tuyisenge et al., 2018)

Parameters:

  • data (array) – Matrix containing your data with shape nChannels x nSamples

  • chRegions (array of strings) – Vector containing name of your channels

  • path (string) – String of the path where you want to store figures

  • pathtbl (string) – Path where the excel file is stored

  • sub (string) – IDs of the patient you are analyzing

  • sess (string) – Name of the session

  • save (Boolean, default=1) – =1 if you want to save plot, put = 0 otherwise

Results

Matplotlib plot and value store in the excel file

NEUREQUA.quality_module.hurst_component(data, chRegions, path, pathtbl, sub, sess, save=1)[source]

Compute the Hurst component You can see Tuyisenge et al. (2018) for a detail of the algorithm Typically EEG data have values around 0.7

Parameters:

  • data (array) – Matrix containing your data with shape nChannels x nSamples

  • chRegions (array of strings) – Vectors containing the name of your channels

  • path (string) – Path where you want to store the plots

  • pathtbl (string) – Path where is store your excel file saving results

  • sub (String) – String “sub-XX” where XX is the number of the subject analyzed

  • sess (String) – Name of the session you are analyzing

Return type:

Matplotlib plot