def test_copyfile_kit(tmpdir): """Test copying and renaming KIT files to a new location.""" output_path = str(tmpdir) data_path = op.join(base_path, 'kit', 'tests', 'data') raw_fname = op.join(data_path, 'test.sqd') hpi_fname = op.join(data_path, 'test_mrk.sqd') electrode_fname = op.join(data_path, 'test.elp') headshape_fname = op.join(data_path, 'test.hsp') subject_id = '01' session_id = '01' run = '01' acq = '01' task = 'testing' raw = mne.io.read_raw_kit( raw_fname, mrk=hpi_fname, elp=electrode_fname, hsp=headshape_fname) _, ext = _parse_ext(raw_fname, verbose=True) datatype = _handle_datatype(raw) bids_path = BIDSPath( subject=subject_id, session=session_id, run=run, acquisition=acq, task=task) kit_bids_path = bids_path.copy().update(acquisition=None, datatype=datatype, root=output_path) bids_fname = str(bids_path.copy().update(datatype=datatype, suffix=datatype, extension=ext, root=output_path)) copyfile_kit(raw_fname, bids_fname, subject_id, session_id, task, run, raw._init_kwargs) assert op.exists(bids_fname) _, ext = _parse_ext(hpi_fname, verbose=True) if ext == '.sqd': kit_bids_path.update(suffix='markers', extension='.sqd') assert op.exists(kit_bids_path) elif ext == '.mrk': kit_bids_path.update(suffix='markers', extension='.mrk') assert op.exists(kit_bids_path) if op.exists(electrode_fname): task, run, key = None, None, 'ELP' elp_ext = '.pos' elp_fname = BIDSPath( subject=subject_id, session=session_id, task=task, run=run, acquisition=key, suffix='headshape', extension=elp_ext, datatype='meg', root=output_path) assert op.exists(elp_fname) if op.exists(headshape_fname): task, run, key = None, None, 'HSP' hsp_ext = '.pos' hsp_fname = BIDSPath( subject=subject_id, session=session_id, task=task, run=run, acquisition=key, suffix='headshape', extension=hsp_ext, datatype='meg', root=output_path) assert op.exists(hsp_fname)
def copyfile_kit(src, dest, subject_id, session_id, task, run, _init_kwargs): """Copy and rename KIT files to a new location. Parameters ---------- src : str Path to the source raw .con or .sqd folder. dest : str Path to the destination of the new bids folder. subject_id : str | None The subject ID. Corresponds to "sub". session_id : str | None The session identifier. Corresponds to "ses". task : str | None The task identifier. Corresponds to "task". run : int | None The run number. Corresponds to "run". _init_kwargs : dict Extract information of marker and headpoints """ # create parent directories in case it does not exist yet _mkdir_p(op.dirname(dest)) # KIT data requires the marker file to be copied over too sh.copyfile(src, dest) data_path = op.split(dest)[0] datatype = 'meg' if 'mrk' in _init_kwargs: hpi = _init_kwargs['mrk'] acq_map = dict() if isinstance(hpi, list): if _get_mrk_meas_date(hpi[0]) > _get_mrk_meas_date(hpi[1]): raise ValueError('Markers provided in incorrect order.') _, marker_ext = _parse_ext(hpi[0]) acq_map = dict(zip(['pre', 'post'], hpi)) else: _, marker_ext = _parse_ext(hpi) acq_map[None] = hpi for key, value in acq_map.items(): marker_path = BIDSPath( subject=subject_id, session=session_id, task=task, run=run, acquisition=key, suffix='markers', extension=marker_ext, datatype=datatype) sh.copyfile(value, op.join(data_path, marker_path.basename)) for acq in ['elp', 'hsp']: if acq in _init_kwargs: position_file = _init_kwargs[acq] task, run, acq = None, None, acq.upper() position_ext = '.pos' position_path = BIDSPath( subject=subject_id, session=session_id, task=task, run=run, acquisition=acq, suffix='headshape', extension=position_ext, datatype=datatype) sh.copyfile(position_file, op.join(data_path, position_path.basename))
def copyfile_eeglab(src, dest): """Copy a EEGLAB files to a new location and adjust pointer to '.fdt' file. Some EEGLAB .set files come with a .fdt binary file that contains the data. When moving a .set file, we need to check for an associated .fdt file and move it to an appropriate location as well as update an internal pointer within the .set file. Parameters ---------- src : str Path to the source raw .set file. dest : str Path to the destination of the new .set file. """ # Get extenstion of the EEGLAB file fname_src, ext_src = _parse_ext(src) fname_dest, ext_dest = _parse_ext(dest) if ext_src != ext_dest: raise ValueError('Need to move data with same extension' f' but got {ext_src}, {ext_dest}') # Extract matlab struct "EEG" from EEGLAB file mat = loadmat(src, squeeze_me=False, chars_as_strings=False, mat_dtype=False, struct_as_record=True) if 'EEG' not in mat: raise ValueError(f'Could not find "EEG" field in {src}') eeg = mat['EEG'] # If the data field is a string, it points to a .fdt file in src dir data = eeg[0][0]['data'] if all([item in data[0, -4:] for item in '.fdt']): head, tail = op.split(src) fdt_pointer = ''.join(data.tolist()[0]) fdt_path = op.join(head, fdt_pointer) fdt_name, fdt_ext = _parse_ext(fdt_path) if fdt_ext != '.fdt': raise IOError('Expected extension .fdt for linked data but found' f' {fdt_ext}') # Copy the fdt file and give it a new name sh.copyfile(fdt_path, fname_dest + '.fdt') # Now adjust the pointer in the set file head, tail = op.split(fname_dest + '.fdt') mat['EEG'][0][0]['data'] = tail savemat(dest, mat, appendmat=False) # If no .fdt file, simply copy the .set file, no modifications necessary else: sh.copyfile(src, dest)
def _get_brainvision_paths(vhdr_path): """Get the .eeg and .vmrk file paths from a BrainVision header file. Parameters ---------- vhdr_path : str Path to the header file. Returns ------- paths : tuple Paths to the .eeg file at index 0 and the .vmrk file at index 1 of the returned tuple. """ fname, ext = _parse_ext(vhdr_path) if ext != '.vhdr': raise ValueError(f'Expecting file ending in ".vhdr",' f' but got {ext}') # Header file seems fine # extract encoding from brainvision header file, or default to utf-8 enc = _get_brainvision_encoding(vhdr_path) # ..and read it with open(vhdr_path, 'r', encoding=enc) as f: lines = f.readlines() # Try to find data file .eeg eeg_file_match = re.search(r'DataFile=(.*\.eeg)', ' '.join(lines)) if not eeg_file_match: raise ValueError('Could not find a .eeg file link in' f' {vhdr_path}') else: eeg_file = eeg_file_match.groups()[0] # Try to find marker file .vmrk vmrk_file_match = re.search(r'MarkerFile=(.*\.vmrk)', ' '.join(lines)) if not vmrk_file_match: raise ValueError('Could not find a .vmrk file link in' f' {vhdr_path}') else: vmrk_file = vmrk_file_match.groups()[0] # Make sure we are dealing with file names as is customary, not paths # Paths are problematic when copying the files to another system. Instead, # always use the file name and keep the file triplet in the same directory assert os.sep not in eeg_file assert os.sep not in vmrk_file # Assert the paths exist head, tail = op.split(vhdr_path) eeg_file_path = op.join(head, eeg_file) vmrk_file_path = op.join(head, vmrk_file) assert op.exists(eeg_file_path) assert op.exists(vmrk_file_path) # Return the paths return (eeg_file_path, vmrk_file_path)
def test_parse_ext(): """Test the file extension extraction.""" f = 'sub-05_task-matchingpennies.vhdr' fname, ext = _parse_ext(f) assert fname == 'sub-05_task-matchingpennies' assert ext == '.vhdr' # Test for case where no extension: assume BTI format f = 'sub-01_task-rest' fname, ext = _parse_ext(f) assert fname == f assert ext == '.pdf' # Get a .nii.gz file f = 'sub-01_task-rest.nii.gz' fname, ext = _parse_ext(f) assert fname == 'sub-01_task-rest' assert ext == '.nii.gz'
def _replace_ext(fname, ext, verbose=False): """Replace the extension of the fname with the passed extension.""" if verbose: print(f"Trying to replace {fname} with extension {ext}") fname, _ext = _parse_ext(fname, verbose=verbose) if not ext.startswith("."): ext = "." + ext return fname + ext
def _add_desc_to_bids_fname(bids_fname, description, verbose: bool = True): if "desc" in str(bids_fname): return bids_fname bids_fname, ext = _parse_ext(bids_fname, verbose) # split by the datatype datatype = bids_fname.split("_")[-1] source_bids_fname = bids_fname.split(f"_{datatype}")[0] result_fname = source_bids_fname + f"_desc-{description}" + f"_{datatype}" + ext return result_fname
def _read_raw(raw_fpath, electrode=None, hsp=None, hpi=None, allow_maxshield=False, config=None, **kwargs): """Read a raw file into MNE, making inferences based on extension.""" _, ext = _parse_ext(raw_fpath) # KIT systems if ext in ['.con', '.sqd']: raw = io.read_raw_kit(raw_fpath, elp=electrode, hsp=hsp, mrk=hpi, preload=False, **kwargs) # BTi systems elif ext == '.pdf': raw = io.read_raw_bti(raw_fpath, config_fname=config, head_shape_fname=hsp, preload=False, **kwargs) elif ext == '.fif': raw = reader[ext](raw_fpath, allow_maxshield, **kwargs) elif ext in ['.ds', '.vhdr', '.set', '.edf', '.bdf', '.EDF']: raw_fpath = Path(raw_fpath) # handle EDF extension upper/lower casing if ext == '.edf' and not raw_fpath.exists(): raw_fpath = raw_fpath.with_suffix('.EDF') elif ext == '.EDF' and not raw_fpath.exists(): raw_fpath = raw_fpath.with_suffix('.edf') raw = reader[ext](raw_fpath, **kwargs) # MEF and NWB are allowed, but not yet implemented elif ext in ['.mef', '.nwb']: raise ValueError(f'Got "{ext}" as extension. This is an allowed ' f'extension but there is no IO support for this ' f'file format yet.') # No supported data found ... # --------------------------- else: raise ValueError(f'Raw file name extension must be one ' f'of {ALLOWED_DATATYPE_EXTENSIONS}\n' f'Got {ext}') return raw
def _read_raw(raw_path, electrode=None, hsp=None, hpi=None, allow_maxshield=False, config_path=None, **kwargs): """Read a raw file into MNE, making inferences based on extension.""" _, ext = _parse_ext(raw_path) # KIT systems if ext in ['.con', '.sqd']: raw = io.read_raw_kit(raw_path, elp=electrode, hsp=hsp, mrk=hpi, preload=False, **kwargs) # BTi systems elif ext == '.pdf': raw = io.read_raw_bti( pdf_fname=str(raw_path), # FIXME MNE should accept Path! config_fname=str(config_path), # FIXME MNE should accept Path! head_shape_fname=hsp, preload=False, **kwargs) elif ext == '.fif': raw = reader[ext](raw_path, allow_maxshield, **kwargs) elif ext in ['.ds', '.vhdr', '.set', '.edf', '.bdf', '.EDF', '.snirf']: if (ext == '.snirf' and not check_version('mne', '1.0')): # pragma: no cover raise RuntimeError( 'fNIRS support in MNE-BIDS requires MNE-Python version 1.0') raw_path = Path(raw_path) raw = reader[ext](raw_path, **kwargs) # MEF and NWB are allowed, but not yet implemented elif ext in ['.mef', '.nwb']: raise ValueError(f'Got "{ext}" as extension. This is an allowed ' f'extension but there is no IO support for this ' f'file format yet.') # No supported data found ... # --------------------------- else: raise ValueError(f'Raw file name extension must be one ' f'of {ALLOWED_DATATYPE_EXTENSIONS}\n' f'Got {ext}') return raw
def save(self, fpath: Union[str, Path]): """Save ResultInfo as a JSON dictionary. Parameters ---------- fpath : str | pathlib.Path The filepath to save the ResultInfo data structure as JSON. """ fname, ext = _parse_ext(fpath, verbose=False) if ext != ".json": raise RuntimeError("Saving Result Info metadata " f"as {ext} is not supported. " "Please use .json") with open(fpath, "w") as fout: json.dump(self, fout, cls=NumpyEncoder, indent=4, sort_keys=True)
def _summarize_channels_tsv(root, scans_fpaths, verbose=True): """Summarize channels.tsv data in BIDS root directory. Currently, summarizes all REQUIRED components of channels data, and some RECOMMENDED and OPTIONAL components. Parameters ---------- root : str | pathlib.Path The path of the root of the BIDS compatible folder. scans_fpaths : list A list of all *_scans.tsv files in ``root``. The summary will occur for all scans listed in the *_scans.tsv files. verbose : bool Returns ------- template_dict : dict A dictionary of values for various template strings. """ root = Path(root) # keep track of channel type, status ch_status_count = {'bad': [], 'good': []} ch_count = [] # loop through each scan for scan_fpath in scans_fpaths: # load in the scans.tsv file # and read metadata for each scan scans_tsv = _from_tsv(scan_fpath) scans = scans_tsv['filename'] for scan in scans: # summarize metadata of recordings bids_path, _ = _parse_ext(scan) datatype = op.dirname(scan) if datatype not in ['meg', 'eeg', 'ieeg']: continue # convert to BIDS Path params = get_entities_from_fname(bids_path) bids_path = BIDSPath(root=root, **params) # XXX: improve to allow emptyroom if bids_path.subject == 'emptyroom': continue channels_fname = _find_matching_sidecar(bids_path=bids_path, suffix='channels', extension='.tsv') # summarize channels.tsv channels_tsv = _from_tsv(channels_fname) for status in ch_status_count.keys(): ch_status = [ ch for ch in channels_tsv['status'] if ch == status ] ch_status_count[status].append(len(ch_status)) ch_count.append(len(channels_tsv['name'])) # create summary template strings for status template_dict = { 'mean_chs': np.mean(ch_count), 'std_chs': np.std(ch_count), 'mean_good_chs': np.mean(ch_status_count['good']), 'std_good_chs': np.std(ch_status_count['good']), 'mean_bad_chs': np.mean(ch_status_count['bad']), 'std_bad_chs': np.std(ch_status_count['bad']), } for key, val in template_dict.items(): template_dict[key] = round(val, 2) return template_dict
def _summarize_sidecar_json(root, scans_fpaths, verbose=True): """Summarize scans in BIDS root directory. Parameters ---------- root : str | pathlib.Path The path of the root of the BIDS compatible folder. scans_fpaths : list A list of all *_scans.tsv files in ``root``. The summary will occur for all scans listed in the *_scans.tsv files. verbose : bool Set verbose output to true or false. Returns ------- template_dict : dict A dictionary of values for various template strings. """ n_scans = 0 powerlinefreqs, sfreqs = set(), set() manufacturers = set() length_recordings = [] # loop through each scan for scan_fpath in scans_fpaths: # load in the scans.tsv file # and read metadata for each scan scans_tsv = _from_tsv(scan_fpath) scans = scans_tsv['filename'] for scan in scans: # summarize metadata of recordings bids_path, ext = _parse_ext(scan) datatype = op.dirname(scan) if datatype not in ALLOWED_DATATYPES: continue n_scans += 1 # convert to BIDS Path params = get_entities_from_fname(bids_path) bids_path = BIDSPath(root=root, **params) # XXX: improve to allow emptyroom if bids_path.subject == 'emptyroom': continue sidecar_fname = _find_matching_sidecar(bids_path=bids_path, suffix=datatype, extension='.json') with open(sidecar_fname, 'r', encoding='utf-8-sig') as fin: sidecar_json = json.load(fin) # aggregate metadata from each scan # REQUIRED kwargs sfreq = sidecar_json['SamplingFrequency'] powerlinefreq = str(sidecar_json['PowerLineFrequency']) software_filters = sidecar_json.get('SoftwareFilters') if not software_filters: software_filters = 'n/a' # RECOMMENDED kwargs manufacturer = sidecar_json.get('Manufacturer', 'n/a') record_duration = sidecar_json.get('RecordingDuration', 'n/a') sfreqs.add(str(np.round(sfreq, 2))) powerlinefreqs.add(str(powerlinefreq)) if manufacturer != 'n/a': manufacturers.add(manufacturer) length_recordings.append(record_duration) # XXX: length summary is only allowed, if no 'n/a' was found if any([dur == 'n/a' for dur in length_recordings]): length_recordings = None template_dict = { 'n_scans': n_scans, 'manufacturer': list(manufacturers), 'sfreq': sfreqs, 'powerlinefreq': powerlinefreqs, 'software_filters': software_filters, 'length_recordings': length_recordings, } return template_dict
def copyfile_brainvision(vhdr_src, vhdr_dest, anonymize=None, verbose=False): """Copy a BrainVision file triplet to a new location and repair links. The BrainVision file format consists of three files: .vhdr, .eeg, and .vmrk The .eeg and .vmrk files associated with the .vhdr file will be given names as in `vhdr_dest` with adjusted extensions. Internal file pointers will be fixed. Parameters ---------- vhdr_src : str The src path of the .vhdr file to be copied. vhdr_dest : str The destination path of the .vhdr file. anonymize : dict | None If None (default), no anonymization is performed. If dict, data will be anonymized depending on the keys provided with the dict: `daysback` is a required key, `keep_his` is an optional key. `daysback` : int Number of days by which to move back the recording date in time. In studies with multiple subjects the relative recording date differences between subjects can be kept by using the same number of `daysback` for all subject anonymizations. `daysback` should be great enough to shift the date prior to 1925 to conform with BIDS anonymization rules. `keep_his` : bool By default (False), all subject information next to the recording date will be overwritten as well. If True, keep subject information apart from the recording date. verbose : bool Determine whether results should be logged. Defaults to False. See Also -------- mne.io.anonymize_info """ # Get extenstion of the brainvision file fname_src, ext_src = _parse_ext(vhdr_src) fname_dest, ext_dest = _parse_ext(vhdr_dest) if ext_src != ext_dest: raise ValueError(f'Need to move data with same extension' f' but got "{ext_src}", "{ext_dest}"') eeg_file_path, vmrk_file_path = _get_brainvision_paths(vhdr_src) # extract encoding from brainvision header file, or default to utf-8 enc = _get_brainvision_encoding(vhdr_src, verbose) # Copy data .eeg ... no links to repair sh.copyfile(eeg_file_path, fname_dest + '.eeg') # Write new header and marker files, fixing the file pointer links # For that, we need to replace an old "basename" with a new one # assuming that all .eeg, .vhdr, .vmrk share one basename __, basename_src = op.split(fname_src) assert basename_src + '.eeg' == op.split(eeg_file_path)[-1] assert basename_src + '.vmrk' == op.split(vmrk_file_path)[-1] __, basename_dest = op.split(fname_dest) search_lines = ['DataFile=' + basename_src + '.eeg', 'MarkerFile=' + basename_src + '.vmrk'] with open(vhdr_src, 'r', encoding=enc) as fin: with open(vhdr_dest, 'w', encoding=enc) as fout: for line in fin.readlines(): if line.strip() in search_lines: line = line.replace(basename_src, basename_dest) fout.write(line) with open(vmrk_file_path, 'r', encoding=enc) as fin: with open(fname_dest + '.vmrk', 'w', encoding=enc) as fout: for line in fin.readlines(): if line.strip() in search_lines: line = line.replace(basename_src, basename_dest) fout.write(line) if anonymize is not None: raw = read_raw_brainvision(vhdr_src, preload=False, verbose=0) daysback, keep_his = _check_anonymize(anonymize, raw, '.vhdr') raw.info = anonymize_info(raw.info, daysback=daysback, keep_his=keep_his) _anonymize_brainvision(fname_dest + '.vhdr', date=raw.info['meas_date']) if verbose: for ext in ['.eeg', '.vhdr', '.vmrk']: _, fname = os.path.split(fname_dest + ext) dirname = op.dirname(op.realpath(vhdr_dest)) print(f'Created "{fname}" in "{dirname}".') if anonymize: print('Anonymized all dates in VHDR and VMRK.')
def copyfile_edf(src, dest, anonymize=None): """Copy an EDF, EDF+, or BDF file to a new location, optionally anonymize. .. warning:: EDF/EDF+/BDF files contain two fields for recording dates: A generic "startdate" field that supports only 2-digit years, and a "Startdate" field as part of the "local recording identification", which supports 4-digit years. If you want to anonymize your file, MNE-BIDS will set the "startdate" field to 85 (i.e., 1985), the earliest possible date for that field. However, the "Startdate" field in the file's "local recording identification" and the date in the session's corresponding ``scans.tsv`` will be set correctly according to the argument provided to the ``anonymize`` parameter. Note that it is possible that not all EDF/EDF+/BDF reading software parses the accurate recording date, and that for some reading software, the wrong year (1985) may be parsed. Parameters ---------- src : str | pathlib.Path The source path of the .edf or .bdf file to be copied. dest : str | pathlib.Path The destination path of the .edf or .bdf file. anonymize : dict | None If None (default), no anonymization is performed. If dict, data will be anonymized depending on the keys provided with the dict: `daysback` is a required key, `keep_his` is an optional key. `daysback` : int Number of days by which to move back the recording date in time. In studies with multiple subjects the relative recording date differences between subjects can be kept by using the same number of `daysback` for all subject anonymizations. `daysback` should be great enough to shift the date prior to 1925 to conform with BIDS anonymization rules. Due to limitations of the EDF/BDF format, the year of the anonymized date will always be set to 1985 in the 'startdate' field of the file. The correctly-shifted year will be written to the 'local recording identification' region of the file header, which may not be parsed by all EDF/EDF+/BDF reader softwares. `keep_his` : bool By default (False), all subject information next to the recording date will be overwritten as well. If True, keep subject information apart from the recording date. Participant names and birthdates will always be anonymized if present, regardless of this setting. See Also -------- mne.io.anonymize_info copyfile_brainvision copyfile_bti copyfile_ctf copyfile_eeglab copyfile_kit """ # Ensure source & destination extensions are the same fname_src, ext_src = _parse_ext(src) fname_dest, ext_dest = _parse_ext(dest) if ext_src != ext_dest: raise ValueError(f'Need to move data with same extension, ' f' but got "{ext_src}" and "{ext_dest}"') # Copy data prior to any anonymization sh.copyfile(src, dest) # Anonymize EDF/BDF data, if requested if anonymize is not None: if ext_src == '.bdf': raw = read_raw_bdf(dest, preload=False, verbose=0) elif ext_src == '.edf': raw = read_raw_edf(dest, preload=False, verbose=0) else: raise ValueError('Unsupported file type ({0})'.format(ext_src)) # Get subject info, recording info, and recording date with open(dest, 'rb') as f: f.seek(8) # id_info field starts 8 bytes in id_info = f.read(80).decode('ascii').rstrip() rec_info = f.read(80).decode('ascii').rstrip() # Parse metadata from file if len(id_info) == 0 or len(id_info.split(' ')) != 4: id_info = "X X X X" if len(rec_info) == 0 or len(rec_info.split(' ')) != 5: rec_info = "Startdate X X X X" pid, sex, birthdate, name = id_info.split(' ') start_date, admin_code, tech, equip = rec_info.split(' ')[1:5] # Try to anonymize the recording date daysback, keep_his = _check_anonymize(anonymize, raw, '.edf') anonymize_info(raw.info, daysback=daysback, keep_his=keep_his) start_date = '01-JAN-1985' meas_date = '01.01.85' # Anonymize ID info and write to file if keep_his: # Always remove participant birthdate and name to be safe id_info = [pid, sex, "X", "X"] rec_info = ["Startdate", start_date, admin_code, tech, equip] else: id_info = ["0", "X", "X", "X"] rec_info = ["Startdate", start_date, "X", "mne-bids_anonymize", "X"] with open(dest, 'r+b') as f: f.seek(8) # id_info field starts 8 bytes in f.write(bytes(" ".join(id_info).ljust(80), 'ascii')) f.write(bytes(" ".join(rec_info).ljust(80), 'ascii')) f.write(bytes(meas_date, 'ascii'))
def get_head_mri_trans(bids_path, extra_params=None, t1_bids_path=None, fs_subject=None, fs_subjects_dir=None, *, kind=None, verbose=None): """Produce transformation matrix from MEG and MRI landmark points. Will attempt to read the landmarks of Nasion, LPA, and RPA from the sidecar files of (i) the MEG and (ii) the T1-weighted MRI data. The two sets of points will then be used to calculate a transformation matrix from head coordinates to MRI coordinates. .. note:: The MEG and MRI data need **not** necessarily be stored in the same session or even in the same BIDS dataset. See the ``t1_bids_path`` parameter for details. Parameters ---------- bids_path : BIDSPath The path of the electrophysiology recording. If ``datatype`` and ``suffix`` are not present, they will be set to ``'meg'``, and a warning will be raised. .. versionchanged:: 0.10 A warning is raised it ``datatype`` or ``suffix`` are not set. extra_params : None | dict Extra parameters to be passed to :func:`mne.io.read_raw` when reading the MEG file. t1_bids_path : BIDSPath | None If ``None`` (default), will try to discover the T1-weighted MRI file based on the name and location of the MEG recording specified via the ``bids_path`` parameter. Alternatively, you explicitly specify which T1-weighted MRI scan to use for extraction of MRI landmarks. To do that, pass a :class:`mne_bids.BIDSPath` pointing to the scan. Use this parameter e.g. if the T1 scan was recorded during a different session than the MEG. It is even possible to point to a T1 image stored in an entirely different BIDS dataset than the MEG data. fs_subject : str The subject identifier used for FreeSurfer. .. versionchanged:: 0.10 Does not default anymore to ``bids_path.subject`` if ``None``. fs_subjects_dir : path-like | None The FreeSurfer subjects directory. If ``None``, defaults to the ``SUBJECTS_DIR`` environment variable. .. versionadded:: 0.8 kind : str | None The suffix of the anatomical landmark names in the JSON sidecar. A suffix might be present e.g. to distinguish landmarks between sessions. If provided, should not include a leading underscore ``_``. For example, if the landmark names in the JSON sidecar file are ``LPA_ses-1``, ``RPA_ses-1``, ``NAS_ses-1``, you should pass ``'ses-1'`` here. If ``None``, no suffix is appended, the landmarks named ``Nasion`` (or ``NAS``), ``LPA``, and ``RPA`` will be used. .. versionadded:: 0.10 %(verbose)s Returns ------- trans : mne.transforms.Transform The data transformation matrix from head to MRI coordinates. """ if not has_nibabel(): # pragma: no cover raise ImportError('This function requires nibabel.') import nibabel as nib if not isinstance(bids_path, BIDSPath): raise RuntimeError('"bids_path" must be a BIDSPath object. Please ' 'instantiate using mne_bids.BIDSPath().') # check root available meg_bids_path = bids_path.copy() del bids_path if meg_bids_path.root is None: raise ValueError('The root of the "bids_path" must be set. ' 'Please use `bids_path.update(root="<root>")` ' 'to set the root of the BIDS folder to read.') # if the bids_path is underspecified, only get info for MEG data if meg_bids_path.datatype is None: meg_bids_path.datatype = 'meg' warn( 'bids_path did not have a datatype set. Assuming "meg". This ' 'will raise an exception in the future.', module='mne_bids', category=DeprecationWarning) if meg_bids_path.suffix is None: meg_bids_path.suffix = 'meg' warn( 'bids_path did not have a suffix set. Assuming "meg". This ' 'will raise an exception in the future.', module='mne_bids', category=DeprecationWarning) # Get the sidecar file for MRI landmarks t1w_bids_path = ((meg_bids_path if t1_bids_path is None else t1_bids_path).copy().update(datatype='anat', suffix='T1w', task=None)) t1w_json_path = _find_matching_sidecar(bids_path=t1w_bids_path, extension='.json', on_error='ignore') del t1_bids_path if t1w_json_path is not None: t1w_json_path = Path(t1w_json_path) if t1w_json_path is None or not t1w_json_path.exists(): raise FileNotFoundError( f'Did not find T1w JSON sidecar file, tried location: ' f'{t1w_json_path}') for extension in ('.nii', '.nii.gz'): t1w_path_candidate = t1w_json_path.with_suffix(extension) if t1w_path_candidate.exists(): t1w_bids_path = get_bids_path_from_fname(fname=t1w_path_candidate) break if not t1w_bids_path.fpath.exists(): raise FileNotFoundError( f'Did not find T1w recording file, tried location: ' f'{t1w_path_candidate.name.replace(".nii.gz", "")}[.nii, .nii.gz]') # Get MRI landmarks from the JSON sidecar t1w_json = json.loads(t1w_json_path.read_text(encoding='utf-8')) mri_coords_dict = t1w_json.get('AnatomicalLandmarkCoordinates', dict()) # landmarks array: rows: [LPA, NAS, RPA]; columns: [x, y, z] suffix = f"_{kind}" if kind is not None else "" mri_landmarks = np.full((3, 3), np.nan) for landmark_name, coords in mri_coords_dict.items(): if landmark_name.upper() == ('LPA' + suffix).upper(): mri_landmarks[0, :] = coords elif landmark_name.upper() == ('RPA' + suffix).upper(): mri_landmarks[2, :] = coords elif (landmark_name.upper() == ('NAS' + suffix).upper() or landmark_name.lower() == ('nasion' + suffix).lower()): mri_landmarks[1, :] = coords else: continue if np.isnan(mri_landmarks).any(): raise RuntimeError( f'Could not extract fiducial points from T1w sidecar file: ' f'{t1w_json_path}\n\n' f'The sidecar file SHOULD contain a key ' f'"AnatomicalLandmarkCoordinates" pointing to an ' f'object with the keys "LPA", "NAS", and "RPA". ' f'Yet, the following structure was found:\n\n' f'{mri_coords_dict}') # The MRI landmarks are in "voxels". We need to convert them to the # Neuromag RAS coordinate system in order to compare them with MEG # landmarks. See also: `mne_bids.write.write_anat` if fs_subject is None: warn( 'Passing "fs_subject=None" has been deprecated and will raise ' 'an error in future versions. Please explicitly specify the ' 'FreeSurfer subject name.', DeprecationWarning) fs_subject = f'sub-{meg_bids_path.subject}' fs_subjects_dir = get_subjects_dir(fs_subjects_dir, raise_error=False) fs_t1_path = Path(fs_subjects_dir) / fs_subject / 'mri' / 'T1.mgz' if not fs_t1_path.exists(): raise ValueError( f"Could not find {fs_t1_path}. Consider running FreeSurfer's " f"'recon-all` for subject {fs_subject}.") fs_t1_mgh = nib.load(str(fs_t1_path)) t1_nifti = nib.load(str(t1w_bids_path.fpath)) # Convert to MGH format to access vox2ras method t1_mgh = nib.MGHImage(t1_nifti.dataobj, t1_nifti.affine) # convert to scanner RAS mri_landmarks = apply_trans(t1_mgh.header.get_vox2ras(), mri_landmarks) # convert to FreeSurfer T1 voxels (same scanner RAS as T1) mri_landmarks = apply_trans(fs_t1_mgh.header.get_ras2vox(), mri_landmarks) # now extract transformation matrix and put back to RAS coordinates of MRI vox2ras_tkr = fs_t1_mgh.header.get_vox2ras_tkr() mri_landmarks = apply_trans(vox2ras_tkr, mri_landmarks) mri_landmarks = mri_landmarks * 1e-3 # Get MEG landmarks from the raw file _, ext = _parse_ext(meg_bids_path) if extra_params is None: extra_params = dict() if ext == '.fif': extra_params['allow_maxshield'] = True raw = read_raw_bids(bids_path=meg_bids_path, extra_params=extra_params) if (raw.get_montage() is None or raw.get_montage().get_positions() is None or any([ raw.get_montage().get_positions()[fid_key] is None for fid_key in ('nasion', 'lpa', 'rpa') ])): raise RuntimeError( f'Could not extract fiducial points from ``raw`` file: ' f'{meg_bids_path}\n\n' f'The ``raw`` file SHOULD contain digitization points ' 'for the nasion and left and right pre-auricular points ' 'but none were found') pos = raw.get_montage().get_positions() meg_landmarks = np.asarray((pos['lpa'], pos['nasion'], pos['rpa'])) # Given the two sets of points, fit the transform trans_fitted = fit_matched_points(src_pts=meg_landmarks, tgt_pts=mri_landmarks) trans = mne.transforms.Transform(fro='head', to='mri', trans=trans_fitted) return trans
def get_head_mri_trans(bids_path, extra_params=None, t1_bids_path=None): """Produce transformation matrix from MEG and MRI landmark points. Will attempt to read the landmarks of Nasion, LPA, and RPA from the sidecar files of (i) the MEG and (ii) the T1-weighted MRI data. The two sets of points will then be used to calculate a transformation matrix from head coordinates to MRI coordinates. .. note:: The MEG and MRI data need **not** necessarily be stored in the same session or even in the same BIDS dataset. See the ``t1_bids_path`` parameter for details. Parameters ---------- bids_path : mne_bids.BIDSPath The path of the MEG recording. extra_params : None | dict Extra parameters to be passed to :func:`mne.io.read_raw` when reading the MEG file. t1_bids_path : mne_bids.BIDSPath | None If ``None`` (default), will try to discover the T1-weighted MRI file based on the name and location of the MEG recording specified via the ``bids_path`` parameter. Alternatively, you explicitly specify which T1-weighted MRI scan to use for extraction of MRI landmarks. To do that, pass a :class:`mne_bids.BIDSPath` pointing to the scan. Use this parameter e.g. if the T1 scan was recorded during a different session than the MEG. It is even possible to point to a T1 image stored in an entirely different BIDS dataset than the MEG data. .. versionadded:: 0.8 Returns ------- trans : mne.transforms.Transform The data transformation matrix from head to MRI coordinates. """ if not has_nibabel(): # pragma: no cover raise ImportError('This function requires nibabel.') import nibabel as nib if not isinstance(bids_path, BIDSPath): raise RuntimeError('"bids_path" must be a BIDSPath object. Please ' 'instantiate using mne_bids.BIDSPath().') # check root available meg_bids_path = bids_path.copy() del bids_path if meg_bids_path.root is None: raise ValueError('The root of the "bids_path" must be set. ' 'Please use `bids_path.update(root="<root>")` ' 'to set the root of the BIDS folder to read.') # only get this for MEG data meg_bids_path.update(datatype='meg', suffix='meg') # Get the sidecar file for MRI landmarks if t1_bids_path is None: t1w_json_path = _find_matching_sidecar(meg_bids_path, suffix='T1w', extension='.json') else: t1_bids_path = t1_bids_path.copy().update(suffix='T1w', datatype='anat') t1w_json_path = _find_matching_sidecar(t1_bids_path, suffix='T1w', extension='.json') # Get MRI landmarks from the JSON sidecar with open(t1w_json_path, 'r', encoding='utf-8') as f: t1w_json = json.load(f) mri_coords_dict = t1w_json.get('AnatomicalLandmarkCoordinates', dict()) # landmarks array: rows: [LPA, NAS, RPA]; columns: [x, y, z] mri_landmarks = np.full((3, 3), np.nan) for landmark_name, coords in mri_coords_dict.items(): if landmark_name.upper() == 'LPA': mri_landmarks[0, :] = coords elif landmark_name.upper() == 'RPA': mri_landmarks[2, :] = coords elif (landmark_name.upper() == 'NAS' or landmark_name.lower() == 'nasion'): mri_landmarks[1, :] = coords else: continue if np.isnan(mri_landmarks).any(): raise RuntimeError( f'Could not extract fiducial points from T1w sidecar file: ' f'{t1w_json_path}\n\n' f'The sidecar file SHOULD contain a key ' f'"AnatomicalLandmarkCoordinates" pointing to an ' f'object with the keys "LPA", "NAS", and "RPA". ' f'Yet, the following structure was found:\n\n' f'{mri_coords_dict}') # The MRI landmarks are in "voxels". We need to convert the to the # neuromag RAS coordinate system in order to compare the with MEG landmarks # see also: `mne_bids.write.write_anat` t1w_path = t1w_json_path.replace('.json', '.nii') if not op.exists(t1w_path): t1w_path += '.gz' # perhaps it is .nii.gz? ... else raise an error if not op.exists(t1w_path): raise RuntimeError( 'Could not find the T1 weighted MRI associated ' 'with "{}". Tried: "{}" but it does not exist.'.format( t1w_json_path, t1w_path)) t1_nifti = nib.load(t1w_path) # Convert to MGH format to access vox2ras method t1_mgh = nib.MGHImage(t1_nifti.dataobj, t1_nifti.affine) # now extract transformation matrix and put back to RAS coordinates of MRI vox2ras_tkr = t1_mgh.header.get_vox2ras_tkr() mri_landmarks = apply_trans(vox2ras_tkr, mri_landmarks) mri_landmarks = mri_landmarks * 1e-3 # Get MEG landmarks from the raw file _, ext = _parse_ext(meg_bids_path) if extra_params is None: extra_params = dict() if ext == '.fif': extra_params['allow_maxshield'] = True raw = read_raw_bids(bids_path=meg_bids_path, extra_params=extra_params) meg_coords_dict = _extract_landmarks(raw.info['dig']) meg_landmarks = np.asarray((meg_coords_dict['LPA'], meg_coords_dict['NAS'], meg_coords_dict['RPA'])) # Given the two sets of points, fit the transform trans_fitted = fit_matched_points(src_pts=meg_landmarks, tgt_pts=mri_landmarks) trans = mne.transforms.Transform(fro='head', to='mri', trans=trans_fitted) return trans
def get_head_mri_trans(bids_path, extra_params=None): """Produce transformation matrix from MEG and MRI landmark points. Will attempt to read the landmarks of Nasion, LPA, and RPA from the sidecar files of (i) the MEG and (ii) the T1 weighted MRI data. The two sets of points will then be used to calculate a transformation matrix from head coordinates to MRI coordinates. Parameters ---------- bids_path : mne_bids.BIDSPath The path of the recording for which to retrieve the transformation. The :class:`mne_bids.BIDSPath` instance passed here **must** have the ``.root`` attribute set. extra_params : None | dict Extra parameters to be passed to MNE read_raw_* functions when reading the lankmarks from the MEG file. If a dict, for example: ``extra_params=dict(allow_maxshield=True)``. Returns ------- trans : mne.transforms.Transform The data transformation matrix from head to MRI coordinates """ if not has_nibabel(): # pragma: no cover raise ImportError('This function requires nibabel.') import nibabel as nib if not isinstance(bids_path, BIDSPath): raise RuntimeError('"bids_path" must be a BIDSPath object. Please ' 'instantiate using mne_bids.BIDSPath().') # check root available bids_path = bids_path.copy() bids_root = bids_path.root if bids_root is None: raise ValueError('The root of the "bids_path" must be set. ' 'Please use `bids_path.update(root="<root>")` ' 'to set the root of the BIDS folder to read.') # only get this for MEG data bids_path.update(datatype='meg') # Get the sidecar file for MRI landmarks bids_fname = bids_path.update(suffix='meg', root=bids_root) t1w_json_path = _find_matching_sidecar(bids_fname, suffix='T1w', extension='.json') # Get MRI landmarks from the JSON sidecar with open(t1w_json_path, 'r', encoding='utf-8-sig') as f: t1w_json = json.load(f) mri_coords_dict = t1w_json.get('AnatomicalLandmarkCoordinates', dict()) mri_landmarks = np.asarray( (mri_coords_dict.get('LPA', np.nan), mri_coords_dict.get('NAS', np.nan), mri_coords_dict.get('RPA', np.nan))) if np.isnan(mri_landmarks).any(): raise RuntimeError( 'Could not parse T1w sidecar file: "{}"\n\n' 'The sidecar file MUST contain a key ' '"AnatomicalLandmarkCoordinates" pointing to a ' 'dict with keys "LPA", "NAS", "RPA". ' 'Yet, the following structure was found:\n\n"{}"'.format( t1w_json_path, t1w_json)) # The MRI landmarks are in "voxels". We need to convert the to the # neuromag RAS coordinate system in order to compare the with MEG landmarks # see also: `mne_bids.write.write_anat` t1w_path = t1w_json_path.replace('.json', '.nii') if not op.exists(t1w_path): t1w_path += '.gz' # perhaps it is .nii.gz? ... else raise an error if not op.exists(t1w_path): raise RuntimeError( 'Could not find the T1 weighted MRI associated ' 'with "{}". Tried: "{}" but it does not exist.'.format( t1w_json_path, t1w_path)) t1_nifti = nib.load(t1w_path) # Convert to MGH format to access vox2ras method t1_mgh = nib.MGHImage(t1_nifti.dataobj, t1_nifti.affine) # now extract transformation matrix and put back to RAS coordinates of MRI vox2ras_tkr = t1_mgh.header.get_vox2ras_tkr() mri_landmarks = apply_trans(vox2ras_tkr, mri_landmarks) mri_landmarks = mri_landmarks * 1e-3 # Get MEG landmarks from the raw file _, ext = _parse_ext(bids_fname) if extra_params is None: extra_params = dict() if ext == '.fif': extra_params = dict(allow_maxshield=True) raw = read_raw_bids(bids_path=bids_path, extra_params=extra_params) meg_coords_dict = _extract_landmarks(raw.info['dig']) meg_landmarks = np.asarray((meg_coords_dict['LPA'], meg_coords_dict['NAS'], meg_coords_dict['RPA'])) # Given the two sets of points, fit the transform trans_fitted = fit_matched_points(src_pts=meg_landmarks, tgt_pts=mri_landmarks) trans = mne.transforms.Transform(fro='head', to='mri', trans=trans_fitted) return trans
def copyfile_eeglab(src, dest): """Copy a EEGLAB files to a new location and adjust pointer to '.fdt' file. Some EEGLAB .set files come with a .fdt binary file that contains the data. When moving a .set file, we need to check for an associated .fdt file and move it to an appropriate location as well as update an internal pointer within the .set file. Parameters ---------- src : str | pathlib.Path Path to the source raw .set file. dest : str | pathlib.Path Path to the destination of the new .set file. See Also -------- copyfile_brainvision copyfile_bti copyfile_ctf copyfile_edf copyfile_kit """ if not mne.utils.check_version('scipy', '1.5.0'): # pragma: no cover raise ImportError('SciPy >=1.5.0 is required handling EEGLAB data.') # Get extension of the EEGLAB file _, ext_src = _parse_ext(src) fname_dest, ext_dest = _parse_ext(dest) if ext_src != ext_dest: raise ValueError(f'Need to move data with same extension' f' but got {ext_src}, {ext_dest}') # Load the EEG struct uint16_codec = None eeg = loadmat(file_name=src, simplify_cells=True, appendmat=False, uint16_codec=uint16_codec) oldstyle = False if 'EEG' in eeg: eeg = eeg['EEG'] oldstyle = True if isinstance(eeg['data'], str): # If the data field is a string, it points to a .fdt file in src dir fdt_fname = eeg['data'] assert fdt_fname.endswith('.fdt') head, tail = op.split(src) fdt_path = op.join(head, fdt_fname) # Copy the .fdt file and give it a new name sh.copyfile(fdt_path, fname_dest + '.fdt') # Now adjust the pointer in the .set file head, tail = op.split(fname_dest + '.fdt') eeg['data'] = tail # Save the EEG dictionary as a Matlab struct again mdict = dict(EEG=eeg) if oldstyle else eeg savemat(file_name=dest, mdict=mdict, appendmat=False) else: # If no .fdt file, simply copy the .set file, no modifications # necessary sh.copyfile(src, dest)