NEUREQUA.cognitive_module¶

Attributes¶

`HEADER_LENGTH`
`NCS_SAMPLES_PER_RECORD`
`NCS_RECORD`
`NEV_RECORD`
`VOLT_SCALING`
`MILLIVOLT_SCALING`
`MICROVOLT_SCALING`

Functions¶

`ensure_dir`(→ None)	Create the directory if it does not exist
`read_header`(fid)	Read the raw header data (16 kb) from the file object fid. Restores the position in the file object after reading.
`parse_header`(raw_hdr)	Parse the header string into a dictionnary of name value pairs
`read_records`(fid, record_dtype[, record_skip, count])	Read count records (default all) from the file object fid skipping the first record_skip records.
`parse_neuralynx_time_string`(time_string)	Parse a datetime object from the idiosyncratic time string Neuralynx file headers
`load_nev`(file_path)	Load Events.nev file from Neuralynx acquisition system
`create_epoch`(lfps, Folder[, t_min, t_max, ds_factor])	Create an Epoch structure in MNE based on the Events registered in the .nev of Neuralynx acquisition system
`ensure_raw`(path, sub, sess)	Look if data were already created on the disk or not (.npy file).
`plot_artefact_map`(path, sub, sess)	Plot figure to show the variance of each trial and each channel
`to_json`(dictionary, filename)	Save a dictionnary to a .json file on your disk.
`load_neuralynx_micro`(path, sub, sess[, macro_pattern, ...])	Load intracranial EEG microwire recordings acquired with Neuralynx
`plot_erp`(path, metadata, sub, sess)	Plot Event-related potentials in response to all events loaded from your recording.

Module Contents¶

NEUREQUA.cognitive_module.HEADER_LENGTH = 16384¶

NEUREQUA.cognitive_module.NCS_SAMPLES_PER_RECORD = 512¶

NEUREQUA.cognitive_module.NCS_RECORD¶

NEUREQUA.cognitive_module.NEV_RECORD¶

NEUREQUA.cognitive_module.VOLT_SCALING = (1, 'V')¶

NEUREQUA.cognitive_module.MILLIVOLT_SCALING = (1000, 'mV')¶

NEUREQUA.cognitive_module.MICROVOLT_SCALING = (1000000, 'µV')¶

NEUREQUA.cognitive_module.ensure_dir(path: str) → None¶

Create the directory if it does not exist

Parameters:: path (str) – Path-like where you want to create folder

NEUREQUA.cognitive_module.read_header(fid)¶

Read the raw header data (16 kb) from the file object fid. Restores the position in the file object after reading.

Parameters:: fid (file object) – File object to .ncs file recorded with Neuralynx
Returns:: raw_hdr – Informations about the recording extracted from the Neuralynx header
Return type:: string

NEUREQUA.cognitive_module.parse_header(raw_hdr)¶

Parse the header string into a dictionnary of name value pairs

Parameters:: raw_hdr (string) – Informations about the recording extracted from the Neuralynx header (obtained with read_header)
Returns:: hdr – Informations about the recording but stored in a dictionnary
Return type:: dict

NEUREQUA.cognitive_module.read_records(fid, record_dtype, record_skip=0, count=None)¶

Read count records (default all) from the file object fid skipping the first record_skip records. Restores the position of the file object after reading.

When multiple recordings segment in the .ncs file

Parameters:

fid (file object) – File object of the recording files
record_dtype (np.dtype) – Data type of all objects in the .nev file
record_skip (int (Default=0)) – Record object to skip, if zero it means we include all recordings in the files If = 1 then skip the first one
count (int (Default=None)) – Number of items to read. If None then means -1 and means all items

Returns:

rec – Numpy array extracted from data in text or binary file see https://numpy.org/doc/stable/reference/generated/numpy.fromfile.html

Return type:

np.array

NEUREQUA.cognitive_module.parse_neuralynx_time_string(time_string)¶

Parse a datetime object from the idiosyncratic time string Neuralynx file headers

Parameters:: time_string (string) – String containing time from Neuralynx file headers
Returns:: datetime.datetime – A datetime object is a single object containing all the information from a date object and a time object. see https://docs.python.org/3/library/datetime.html#datetime-objects
Return type:: datetime object

NEUREQUA.cognitive_module.load_nev(file_path)¶

Load Events.nev file from Neuralynx acquisition system

Parameters:: file_path (string or path-like) – Path where the file .nev is stored
Returns:: nev – Dictionnary containing events informations (as TimeStamp, id, ttl values)
Return type:: dict

NEUREQUA.cognitive_module.create_epoch(lfps, Folder, t_min=1, t_max=1, ds_factor=1)¶

Create an Epoch structure in MNE based on the Events registered in the .nev of Neuralynx acquisition system To load the data from the .nev file I used the following library: https://github.com/alafuzof/NeuralynxIO

Parameters:

Folder (string) – Path where your ncs files and the Events.nev files are stored
t_min (float) – Time to include in the baseline (before the onset of event)
t_max (float) – Time to include after the onset of the event

Returns:

epoch_data – Array containing the data of each epoch with 3-D shape (nEpoch x nChannels x nSamples)

Return type:

np.array

NEUREQUA.cognitive_module.ensure_raw(path, sub, sess)¶

Look if data were already created on the disk or not (.npy file). If they were created then load them as a memory mapped object.

Parameters:

path (string or path-like) – Path of the folder where your data are stored
sub (str) – Id of the patient to analyze according to your dataset
sess (str) – Name of the experimental session to analyze

Returns:

lfps – Memory mapped object of the raw data stored on your file (.npy file)

Return type:

np.memmap

NEUREQUA.cognitive_module.plot_artefact_map(path, sub, sess)¶

Plot figure to show the variance of each trial and each channel Enables us to quickly see the channels that are artefacted (e.g., by epileptic activities) and also trials contaminated

Just like the figure 9.B of Mercier et al. (2022)

Parameters:

epoch_data (array) – Matrice with the following shape (nTrials, nChannels, nSamples)
path (String) – Path where you want to store results of this analyses

Return type:

Matplotlib plot containing heatmap and variance of each channels for each trials

NEUREQUA.cognitive_module.to_json(dictionary, filename)¶

Save a dictionnary to a .json file on your disk.

Parameters:

dictionary (dict) – The dictionnary you want to save
filename (str or path-like) – Path and name of the .json file you want to create with the informations contained in dictionary

NEUREQUA.cognitive_module.load_neuralynx_micro(path, sub, sess, macro_pattern='_sub', verbose=True)¶

Load intracranial EEG microwire recordings acquired with Neuralynx in .ncs format into memory, excluding macrocontact channels.

The function reads all .ncs files located in the specified directory, automatically excludes channels whose filename contains the macro- contact pattern, loads the full recording into memory, and returns both a structured MNE Raw object and a raw NumPy array.

Parameters:

path (str) – Path to the directory containing the .ncs recording files.
macro_pattern (str, optional) – Substring used to identify and exclude macrocontact channels from the recording (default: ‘_sub’). Example: if macrocontact files are named ‘LA1_sub.ncs’, setting macro_pattern=’_sub’ will exclude them automatically.
verbose (bool, optional) – If True, prints a summary of the loaded recording upon completion (default: True).

Returns:

raw (mne.io.Raw) – MNE Raw object containing the full microwire recording. Provides access to channel metadata (names, sampling rate, recording duration) and supports MNE-based preprocessing.
data (np.ndarray) – NumPy array of shape (n_channels, n_samples) containing the raw signal values in Volts, loaded entirely into memory.
metadata (dict) –
Dictionary containing key recording parameters:
- ’ch_names’ : list of str, microwire channel labels
- ’n_channels’ : int, number of microwire channels
- ’sfreq’ : float, sampling rate in Hz
- ’duration_s’ : float, recording duration in seconds
- ’n_samples’ : int, total number of samples per channel
- ’macro_pattern’: str, exclusion pattern used

Raises:

FileNotFoundError – If the specified path does not exist or contains no .ncs files.
ValueError – If no microwire channels remain after applying the exclusion pattern (i.e., all channels matched the macro_pattern).

NEUREQUA.cognitive_module.plot_erp(path, metadata, sub, sess)¶

Plot Event-related potentials in response to all events loaded from your recording. Plot the ERPs for each channel that you had.

Parameters:

path (str or path-like) – Path where the .npy file containing your raw data is stored
metadata (dict) – Dictionnary created when loading your data containing informations about the recordings
sub (str) – Id of the patient to analyze
sess (str) – Name of the experimental session to analyze