offspect.input.tms.cmep.smartmove

Smartmove robotic

These recordings come from the smartmove robotic TMS. This input format uses three files:

  • .cnt for EEG

  • .cnt for EMG

  • .txt for Coordinates

Note

Load the TraceData with load_ephys_file() and the Coords with load_documentation_txt()

Data

EEG and EMG data is stored in the native file-format of the eego recording software. It can be loaded with libeep. During robotic TMS, the 64 EEG channels and the 8 EMG channels are stored in separate .cnt files.

Coordinates

During the mapping procedure, the coordinates of the target positions, i.e. where the robot will be moved to, are saved in a documentation.txt-file. Please note that these are the targets for the robotic movement, recorded, not the actual coordinates of stimulation. The actual coordinates at the time of stimulation do not appear to have been stored at all.

Documentation.txt

The file documentation.txt stores the coordinates of each target the robot arm moved to. It does not contain information regarding manual adjustments (i.e. adjusting distance of coil to the head) or the actual coil position at the time of stimulation. Target coordinates are given in medical image coordinates (CT / 3D image).

  • Target counter: Counts the number of successfully reached targets, including this one.

  • Target number: Point number in the total list of all targets.

  • Target label: The ‘name’ of the target point. Usually the same as the target number.

  • X-vector [<m11> <m21> <m31>]

  • Y-vector [<m12> <m22> <m32>]

  • Z-vector [<m13> <m23> <m33>]

  • Position [<x> <y> <z>]

  • Date & time point [dd.mm.yy hh:mm:ss]

  • Experiment name [always ‘TMS exp’]

  • Subject ID [NnVv]

The coordinates of the targets are stored in one or multiple targets_*.sav-files in xml format. The filename of this save file encodes experiment, subject pseudonym, date and hour, e.g.: targets_<experiment>_<VvNn>_20190603_1624.sav. These coordinates are the e.g. the grid of targets predefined before starting the mapping.

The file success.txt stores the coordinates of only the last target the robot arm moved to. The first line reads ‘success’ (move ended at desired position), ‘start’ (move started but not ended) or ‘fail’ (move ended before reaching the target due to error). The second line contains the timestamp of when the status was updated. For line 4 to 10, same notation as in documentation.txt.

The file target_TMS_exp_[NnVv]_[yyyymmdd_hhmm] stores the coordinates of all created targets. It contains the position (<x>, <y> and <z>), matrix operations (<m11>, <m12>… until <m33>) and target label (<label>), each labeled as such.

Module Content

assert_equal_recording_day(eeg_fname, emg_fname)[source]
cut_traces(cntfile, annotation)[source]

cut the tracedate from a matfile given Annotations :type cntfile: Union[str, Path] :param cntfile: the cntfile for cutting the data. must correspond in name to the one specified in the annotation :type cntfile: FileName :type annotation: Dict[str, Any] :param annotation: the annotations specifying e.g. onsets as well as pre and post durations :type annotation: Annotations

Returns

traces (List[TraceData])

is_eeg_file(fname)[source]

return true if this is the eeg-file

is_eegfile_valid(fname)[source]
load_documentation_txt(fname)[source]

load a documentation.txt and return Coords

load_ephys_file(eeg_fname, emg_fname, pre_in_ms=100, post_in_ms=100, select_events=['0001'], select_channel='Ch1')[source]

load the electophysiological data for a specific channel for a smartmove file-pair

Parameters

  • eeg_fname (FileName) – the path to the EEG file. The file is expected to have the following format: VvNn_VvNn_YYYY-MM-DD_HH-MM-SS.cnt

  • emg_fname (FileName) – the path to the EMG file. The file is expected to have the following format: VvNn<qualifier> YYYY-MM-DD_HH-MM-SS.cnt

  • pre_in_ms (float = 100) – how much time before the TMS

  • post_in_ms (float = 100) – how much time after the TMS

  • select_events (List[str] = ["0001"]) – which events indicate the occurence of a TMS-pulse

  • select_channel (str = "Ch1") – the channel to use. Note that EMG channel labes only offer a selection of 'Ch1', 'Ch2', 'Ch3', 'Ch4', 'Ch5', 'Ch6', 'Ch7', 'Ch8', while EEG channels are recording from a standard wavecap and should offer [‘Fp1’, ‘Fpz’, ‘Fp2’, ‘F7’, ‘F3’, ‘Fz’, ‘F4’, ‘F8’, ‘FC5’, ‘FC1’, ‘FC2’, ‘FC6’, ‘M1’, ‘T7’, ‘C3’, ‘Cz’, ‘C4’, ‘T8’, ‘M2’, ‘CP5’, ‘CP1’, ‘CP2’, ‘CP6’, ‘P7’, ‘P3’, ‘Pz’, ‘P4’, ‘P8’, ‘POz’, ‘O1’, ‘O2’, ‘EOG’, ‘AF7’, ‘AF3’, ‘AF4’, ‘AF8’, ‘F5’, ‘F1’, ‘F2’, ‘F6’, ‘FC3’, ‘FCz’, ‘FC4’, ‘C5’, ‘C1’, ‘C2’, ‘C6’, ‘CP3’, ‘CP4’, ‘P5’, ‘P1’, ‘P2’, ‘P6’, ‘PO5’, ‘PO3’, ‘PO4’, ‘PO6’, ‘FT7’, ‘FT8’, ‘TP7’, ‘TP8’, ‘PO7’, ‘PO8’, ‘Oz’] all in reference to Cpz.

Returns

  • Traces (List[TraceData]) – the TraceData for each event fitting to select_events in the file

  • pre_in_samples (int) – how many samples before the trigger

  • post_in_samples (int) – how many samples after the trigger

  • sampling_rate (float) – the sampling rate of the trace

load_triggers(fname)[source]
parse_recording_date(fname)[source]

The eeg cnt-file should have the following format: VvNn_VvNn_YYYY-MM-DD_HH-MM-SS.cnt

prepare_annotations(docfile, cntfiles, channel, pre_in_ms, post_in_ms, select_events=['0001'])[source]

load a documentation.txt and cnt-files and distill annotations from them

Parameters

  • docfile (FileName) – the documentation.txt with the target coordintes

  • cntfiles (List[FileName]) – a list of the .cnt-file with the EEG data and triggers and the the .cnt-file with the EMG data

  • channel (str) – which channel to pick

  • pre_in_ms (float) – how many ms to cut before the tms

  • post_in_ms (float) – how many ms to cut after the tms

Returns

annotation (Annotations) – the annotations for this origin files