NEUREQUA.cognitive_module ========================= .. py:module:: NEUREQUA.cognitive_module Attributes ---------- .. autoapisummary:: NEUREQUA.cognitive_module.HEADER_LENGTH NEUREQUA.cognitive_module.NCS_SAMPLES_PER_RECORD NEUREQUA.cognitive_module.NCS_RECORD NEUREQUA.cognitive_module.NEV_RECORD NEUREQUA.cognitive_module.VOLT_SCALING NEUREQUA.cognitive_module.MILLIVOLT_SCALING NEUREQUA.cognitive_module.MICROVOLT_SCALING Functions --------- .. autoapisummary:: NEUREQUA.cognitive_module.ensure_dir NEUREQUA.cognitive_module.read_header NEUREQUA.cognitive_module.parse_header NEUREQUA.cognitive_module.read_records NEUREQUA.cognitive_module.parse_neuralynx_time_string NEUREQUA.cognitive_module.load_nev NEUREQUA.cognitive_module.create_epoch NEUREQUA.cognitive_module.ensure_raw NEUREQUA.cognitive_module.plot_artefact_map NEUREQUA.cognitive_module.to_json NEUREQUA.cognitive_module.load_neuralynx_micro NEUREQUA.cognitive_module.plot_erp Module Contents --------------- .. py:data:: HEADER_LENGTH :value: 16384 .. py:data:: NCS_SAMPLES_PER_RECORD :value: 512 .. py:data:: NCS_RECORD .. py:data:: NEV_RECORD .. py:data:: VOLT_SCALING :value: (1, 'V') .. py:data:: MILLIVOLT_SCALING :value: (1000, 'mV') .. py:data:: MICROVOLT_SCALING :value: (1000000, 'µV') .. py:function:: ensure_dir(path: str) -> None Create the directory if it does not exist :param path: Path-like where you want to create folder :type path: str .. py:function:: read_header(fid) Read the raw header data (16 kb) from the file object fid. Restores the position in the file object after reading. :param fid: File object to .ncs file recorded with Neuralynx :type fid: file object :returns: **raw_hdr** -- Informations about the recording extracted from the Neuralynx header :rtype: string .. py:function:: parse_header(raw_hdr) Parse the header string into a dictionnary of name value pairs :param raw_hdr: Informations about the recording extracted from the Neuralynx header (obtained with read_header) :type raw_hdr: string :returns: **hdr** -- Informations about the recording but stored in a dictionnary :rtype: dict .. py:function:: 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 :param fid: File object of the recording files :type fid: file object :param record_dtype: Data type of all objects in the .nev file :type record_dtype: np.dtype :param record_skip: Record object to skip, if zero it means we include all recordings in the files If = 1 then skip the first one :type record_skip: int (Default=0) :param count: Number of items to read. If None then means -1 and means all items :type count: int (Default=None) :returns: **rec** -- Numpy array extracted from data in text or binary file see https://numpy.org/doc/stable/reference/generated/numpy.fromfile.html :rtype: np.array .. py:function:: parse_neuralynx_time_string(time_string) Parse a datetime object from the idiosyncratic time string Neuralynx file headers :param time_string: String containing time from Neuralynx file headers :type time_string: string :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 :rtype: datetime object .. py:function:: load_nev(file_path) Load Events.nev file from Neuralynx acquisition system :param file_path: Path where the file .nev is stored :type file_path: string or path-like :returns: **nev** -- Dictionnary containing events informations (as TimeStamp, id, ttl values) :rtype: dict .. py:function:: 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 :param Folder: Path where your ncs files and the Events.nev files are stored :type Folder: string :param t_min: Time to include in the baseline (before the onset of event) :type t_min: float :param t_max: Time to include after the onset of the event :type t_max: float :returns: **epoch_data** -- Array containing the data of each epoch with 3-D shape (nEpoch x nChannels x nSamples) :rtype: np.array .. py:function:: 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. :param path: Path of the folder where your data are stored :type path: string or path-like :param sub: Id of the patient to analyze according to your dataset :type sub: str :param sess: Name of the experimental session to analyze :type sess: str :returns: **lfps** -- Memory mapped object of the raw data stored on your file (.npy file) :rtype: np.memmap .. py:function:: 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) :param epoch_data: Matrice with the following shape (nTrials, nChannels, nSamples) :type epoch_data: array :param path: Path where you want to store results of this analyses :type path: String :rtype: Matplotlib plot containing heatmap and variance of each channels for each trials .. py:function:: to_json(dictionary, filename) Save a dictionnary to a .json file on your disk. :param dictionary: The dictionnary you want to save :type dictionary: dict :param filename: Path and name of the .json file you want to create with the informations contained in dictionary :type filename: str or path-like .. py:function:: 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. :param path: Path to the directory containing the .ncs recording files. :type path: str :param macro_pattern: 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. :type macro_pattern: str, optional :param verbose: If True, prints a summary of the loaded recording upon completion (default: True). :type verbose: bool, optional :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. :raises ValueError: If no microwire channels remain after applying the exclusion pattern (i.e., all channels matched the macro_pattern). .. py:function:: 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. :param path: Path where the .npy file containing your raw data is stored :type path: str or path-like :param metadata: Dictionnary created when loading your data containing informations about the recordings :type metadata: dict :param sub: Id of the patient to analyze :type sub: str :param sess: Name of the experimental session to analyze :type sess: str