def _coordsystem_json(raw,
unit,
orient,
manufacturer,
fname,
overwrite=False,
verbose=True):
"""Create a coordsystem.json file and save it.
Parameters
----------
raw : instance of Raw
The data as MNE-Python Raw object.
unit : str
Units to be used in the coordsystem specification.
orient : str
Used to define the coordinate system for the head coils.
manufacturer : str
Used to define the coordinate system for the MEG sensors.
fname : str
Filename to save the coordsystem.json to.
overwrite : bool
Whether to overwrite the existing file.
Defaults to False.
verbose : bool
Set verbose output to true or false.
"""
dig = raw.info['dig']
coords = _extract_landmarks(dig)
hpi = {d['ident']: d for d in dig if d['kind'] == FIFF.FIFFV_POINT_HPI}
if hpi:
for ident in hpi.keys():
coords['coil%d' % ident] = hpi[ident]['r'].tolist()
coord_frame = set([dig[ii]['coord_frame'] for ii in range(len(dig))])
if len(coord_frame) > 1:
err = 'All HPI and Fiducials must be in the same coordinate frame.'
raise ValueError(err)
fid_json = {
'MEGCoordinateSystem': manufacturer,
'MEGCoordinateUnits': unit, # XXX validate this
'HeadCoilCoordinates': coords,
'HeadCoilCoordinateSystem': orient,
'HeadCoilCoordinateUnits': unit # XXX validate this
}
_write_json(fname, fid_json, overwrite, verbose)
return fname
def _write_dig_bids(bids_path, raw, overwrite=False, verbose=True):
"""Write BIDS formatted DigMontage from Raw instance.
Handles coordinatesystem.json and electrodes.tsv writing
from DigMontage.
Parameters
----------
bids_path : BIDSPath
Path in the BIDS dataset to save the ``electrodes.tsv``
and ``coordsystem.json`` file for. ``datatype``
attribute must be ``eeg``, or ``ieeg``. For ``meg``
data, ``electrodes.tsv`` are not saved.
raw : instance of Raw
The data as MNE-Python Raw object.
overwrite : bool
Whether to overwrite the existing file.
Defaults to False.
verbose : bool
Set verbose output to true or false.
"""
# write electrodes data for iEEG and EEG
unit = "m" # defaults to meters
# get coordinate frame from digMontage
digpoint = raw.info['dig'][0]
if any(digpoint['coord_frame'] != _digpoint['coord_frame']
for _digpoint in raw.info['dig']):
warn("Not all digpoints have the same coordinate frame. "
"Skipping electrodes.tsv writing...")
return
# get the accepted mne-python coordinate frames
coord_frame_int = int(digpoint['coord_frame'])
mne_coord_frame = MNE_FRAME_TO_STR.get(coord_frame_int, None)
coord_frame = MNE_TO_BIDS_FRAMES.get(mne_coord_frame, None)
# create electrodes/coordsystem files using a subset of entities
# that are specified for these files in the specification
coord_file_entities = {
'root': bids_path.root,
'datatype': bids_path.datatype,
'subject': bids_path.subject,
'session': bids_path.session,
'acquisition': bids_path.acquisition,
'space': bids_path.space
}
datatype = bids_path.datatype
electrodes_path = BIDSPath(**coord_file_entities, suffix='electrodes',
extension='.tsv')
coordsystem_path = BIDSPath(**coord_file_entities, suffix='coordsystem',
extension='.json')
if verbose:
print("Writing electrodes file to... ", electrodes_path)
print("Writing coordsytem file to... ", coordsystem_path)
if datatype == "ieeg":
if coord_frame is not None:
# XXX: To improve when mne-python allows coord_frame='unknown'
if coord_frame not in BIDS_IEEG_COORDINATE_FRAMES:
coordsystem_path.update(space=coord_frame)
electrodes_path.update(space=coord_frame)
coord_frame = 'Other'
# Now write the data to the elec coords and the coordsystem
_electrodes_tsv(raw, electrodes_path,
datatype, overwrite, verbose)
_coordsystem_json(raw=raw, unit=unit, hpi_coord_system='n/a',
sensor_coord_system=coord_frame,
fname=coordsystem_path, datatype=datatype,
overwrite=overwrite, verbose=verbose)
else:
# default coordinate frame to mri if not available
warn("Coordinate frame of iEEG coords missing/unknown "
"for {}. Skipping reading "
"in of montage...".format(electrodes_path))
elif datatype == 'eeg':
# We only write EEG electrodes.tsv and coordsystem.json
# if we have LPA, RPA, and NAS available to rescale to a known
# coordinate system frame
coords = _extract_landmarks(raw.info['dig'])
landmarks = set(['RPA', 'NAS', 'LPA']) == set(list(coords.keys()))
# XXX: to be improved to allow rescaling if landmarks are present
# mne-python automatically converts unknown coord frame to head
if coord_frame_int == FIFF.FIFFV_COORD_HEAD and landmarks:
# Now write the data
_electrodes_tsv(raw, electrodes_path, datatype,
overwrite, verbose)
_coordsystem_json(raw=raw, unit='m', hpi_coord_system='n/a',
sensor_coord_system='CapTrak',
fname=coordsystem_path, datatype=datatype,
overwrite=overwrite, verbose=verbose)
else:
warn("Skipping EEG electrodes.tsv... "
"Setting montage not possible if anatomical "
"landmarks (NAS, LPA, RPA) are missing, "
"and coord_frame is not 'head'.")
def _coordsystem_json(*, raw, unit, hpi_coord_system, sensor_coord_system,
fname, datatype, overwrite=False, verbose=True):
"""Create a coordsystem.json file and save it.
Parameters
----------
raw : instance of Raw
The data as MNE-Python Raw object.
unit : str
Units to be used in the coordsystem specification,
as in BIDS_COORDINATE_UNITS.
hpi_coord_system : str
Name of the coordinate system for the head coils.
sensor_coord_system : str
Name of the coordinate system for the sensor positions.
fname : str
Filename to save the coordsystem.json to.
datatype : str
Type of the data recording. Can be ``meg``, ``eeg``,
or ``ieeg``.
overwrite : bool
Whether to overwrite the existing file.
Defaults to False.
verbose : bool
Set verbose output to true or false.
"""
dig = raw.info['dig']
if dig is None:
dig = []
coords = _extract_landmarks(dig)
hpi = {d['ident']: d for d in dig if d['kind'] == FIFF.FIFFV_POINT_HPI}
if hpi:
for ident in hpi.keys():
coords['coil%d' % ident] = hpi[ident]['r'].tolist()
coord_frame = set([dig[ii]['coord_frame'] for ii in range(len(dig))])
if len(coord_frame) > 1: # noqa E501
raise ValueError('All HPI, electrodes, and fiducials must be in the '
'same coordinate frame. Found: "{}"'
.format(coord_frame))
# get the coordinate frame description
sensor_coord_system_descr = (COORD_FRAME_DESCRIPTIONS
.get(sensor_coord_system.lower(), "n/a"))
if sensor_coord_system == 'Other' and verbose:
print('Using the `Other` keyword for the CoordinateSystem field. '
'Please specify the CoordinateSystemDescription field manually.')
# create the coordinate json data structure based on 'datatype'
if datatype == 'meg':
hpi = {d['ident']: d for d in dig if d['kind'] == FIFF.FIFFV_POINT_HPI}
if hpi:
for ident in hpi.keys():
coords['coil%d' % ident] = hpi[ident]['r'].tolist()
fid_json = {
'MEGCoordinateSystem': sensor_coord_system,
'MEGCoordinateUnits': unit, # XXX validate this
'MEGCoordinateSystemDescription': sensor_coord_system_descr,
'HeadCoilCoordinates': coords,
'HeadCoilCoordinateSystem': hpi_coord_system,
'HeadCoilCoordinateUnits': unit # XXX validate this
}
elif datatype == 'eeg':
fid_json = {
'EEGCoordinateSystem': sensor_coord_system,
'EEGCoordinateUnits': unit,
'EEGCoordinateSystemDescription': sensor_coord_system_descr,
'AnatomicalLandmarkCoordinates': coords,
'AnatomicalLandmarkCoordinateSystem': sensor_coord_system,
'AnatomicalLandmarkCoordinateUnits': unit,
}
elif datatype == "ieeg":
fid_json = {
# (Other, Pixels, ACPC)
'iEEGCoordinateSystem': sensor_coord_system,
'iEEGCoordinateSystemDescription': sensor_coord_system_descr,
'iEEGCoordinateUnits': unit, # m (MNE), mm, cm , or pixels
}
_write_json(fname, fid_json, overwrite, verbose)
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 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 _write_coordsystem_json(*,
raw,
unit,
hpi_coord_system,
sensor_coord_system,
fname,
datatype,
overwrite=False,
verbose=True):
"""Create a coordsystem.json file and save it.
Parameters
----------
raw : mne.io.Raw
The data as MNE-Python Raw object.
unit : str
Units to be used in the coordsystem specification,
as in BIDS_COORDINATE_UNITS.
hpi_coord_system : str
Name of the coordinate system for the head coils.
sensor_coord_system : str | tuple of str
Name of the coordinate system for the sensor positions.
If a tuple of strings, should be in the form:
``(BIDS coordinate frame, MNE coordinate frame)``.
fname : str
Filename to save the coordsystem.json to.
datatype : str
Type of the data recording. Can be ``meg``, ``eeg``,
or ``ieeg``.
overwrite : bool
Whether to overwrite the existing file.
Defaults to False.
verbose : bool
Set verbose output to true or false.
"""
dig = raw.info['dig']
if dig is None:
dig = []
coord_frame = set([dig[ii]['coord_frame'] for ii in range(len(dig))])
if len(coord_frame) > 1: # noqa E501
raise ValueError(
'All HPI, electrodes, and fiducials must be in the '
'same coordinate frame. Found: "{}"'.format(coord_frame))
# get the coordinate frame description
try:
sensor_coord_system, sensor_coord_system_mne = sensor_coord_system
except ValueError:
sensor_coord_system_mne = "n/a"
sensor_coord_system_descr = (BIDS_COORD_FRAME_DESCRIPTIONS.get(
sensor_coord_system.lower(), "n/a"))
if sensor_coord_system == 'Other':
if verbose:
msg = ('Using the `Other` keyword for the CoordinateSystem field. '
'Please specify the CoordinateSystemDescription field '
'manually.')
logger.info(msg)
sensor_coord_system_descr = (BIDS_COORD_FRAME_DESCRIPTIONS.get(
sensor_coord_system_mne.lower(), "n/a"))
coords = _extract_landmarks(dig)
# create the coordinate json data structure based on 'datatype'
if datatype == 'meg':
landmarks = dict(coords)
hpi = {d['ident']: d for d in dig if d['kind'] == FIFF.FIFFV_POINT_HPI}
if hpi:
for ident in hpi.keys():
coords['coil%d' % ident] = hpi[ident]['r'].tolist()
fid_json = {
'MEGCoordinateSystem': sensor_coord_system,
'MEGCoordinateUnits': unit, # XXX validate this
'MEGCoordinateSystemDescription': sensor_coord_system_descr,
'HeadCoilCoordinates': coords,
'HeadCoilCoordinateSystem': hpi_coord_system,
'HeadCoilCoordinateUnits': unit, # XXX validate this
'AnatomicalLandmarkCoordinates': landmarks,
'AnatomicalLandmarkCoordinateSystem': sensor_coord_system,
'AnatomicalLandmarkCoordinateUnits': unit
}
elif datatype == 'eeg':
fid_json = {
'EEGCoordinateSystem': sensor_coord_system,
'EEGCoordinateUnits': unit,
'EEGCoordinateSystemDescription': sensor_coord_system_descr,
'AnatomicalLandmarkCoordinates': coords,
'AnatomicalLandmarkCoordinateSystem': sensor_coord_system,
'AnatomicalLandmarkCoordinateUnits': unit,
}
elif datatype == "ieeg":
fid_json = {
# (Other, Pixels, ACPC)
'iEEGCoordinateSystem': sensor_coord_system,
'iEEGCoordinateSystemDescription': sensor_coord_system_descr,
'iEEGCoordinateUnits': unit, # m (MNE), mm, cm , or pixels
}
# note that any coordsystem.json file shared within sessions
# will be the same across all runs (currently). So
# overwrite is set to True always
# XXX: improve later when BIDS is updated
# check that there already exists a coordsystem.json
if Path(fname).exists() and not overwrite:
with open(fname, 'r', encoding='utf-8-sig') as fin:
coordsystem_dict = json.load(fin)
if fid_json != coordsystem_dict:
raise RuntimeError(
f'Trying to write coordsystem.json, but it already '
f'exists at {fname} and the contents do not match. '
f'You must differentiate this coordsystem.json file '
f'from the existing one, or set "overwrite" to True.')
_write_json(fname, fid_json, overwrite=True, verbose=verbose)
def get_head_mri_trans(bids_basename, bids_root):
"""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_basename : str | BIDSPath
The base filename of the BIDS-compatible file. Typically, this can be
generated using :func:`mne_bids.make_bids_basename`.
bids_root : str | pathlib.Path
Path to root of the BIDS folder
Returns
-------
trans : instance of 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
# convert to BIDS Path
if isinstance(bids_basename, str):
params = _parse_bids_filename(bids_basename, False)
bids_basename = BIDSPath(subject=params.get('sub'),
session=params.get('ses'),
recording=params.get('rec'),
acquisition=params.get('acq'),
processing=params.get('proc'),
space=params.get('space'),
run=params.get('run'),
task=params.get('task'))
# Get the sidecar file for MRI landmarks
bids_fname = bids_basename.get_bids_fname(kind='meg', bids_root=bids_root)
t1w_json_path = _find_matching_sidecar(bids_fname, bids_root, 'T1w.json')
# Get MRI landmarks from the JSON sidecar
with open(t1w_json_path, 'r') 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_basename)
extra_params = None
if ext == '.fif':
extra_params = dict(allow_maxshield=True)
raw = read_raw_bids(bids_basename=bids_basename,
bids_root=bids_root,
extra_params=extra_params,
kind='meg')
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 write_anat(bids_root, subject, t1w, session=None, acquisition=None,
raw=None, trans=None, deface=False, overwrite=False,
verbose=False):
"""Put anatomical MRI data into a BIDS format.
Given a BIDS directory and a T1 weighted MRI scan for a certain subject,
format the MRI scan to be in BIDS format and put it into the correct
location in the bids_dir. If a transformation matrix is supplied, a
sidecar JSON file will be written for the T1 weighted data.
Parameters
----------
bids_root : str
Path to root of the BIDS folder
subject : str
Subject label as in 'sub-<label>', for example: '01'
t1w : str | nibabel image object
Path to a T1 weighted MRI scan of the subject. Can be in any format
readable by nibabel. Can also be a nibabel image object of a T1
weighted MRI scan. Will be written as a .nii.gz file.
session : str | None
The session for `t1w`. Corresponds to "ses"
acquisition: str | None
The acquisition parameters for `t1w`. Corresponds to "acq"
raw : instance of Raw | None
The raw data of `subject` corresponding to `t1w`. If `raw` is None,
`trans` has to be None as well
trans : instance of mne.transforms.Transform | str | None
The transformation matrix from head coordinates to MRI coordinates. Can
also be a string pointing to a .trans file containing the
transformation matrix. If None, no sidecar JSON file will be written
for `t1w`
deface : bool | dict
If False, no defacing is performed.
If True, deface with default parameters.
`trans` and `raw` must not be `None` if True.
If dict, accepts the following keys:
`inset`: how far back in millimeters to start defacing
relative to the nasion (default 20)
`theta`: is the angle of the defacing shear in degrees relative
to the normal to the plane passing through the anatomical
landmarks (default 35).
overwrite : bool
Whether to overwrite existing files or data in files.
Defaults to False.
If overwrite is True, any existing files with the same BIDS parameters
will be overwritten with the exception of the `participants.tsv` and
`scans.tsv` files. For these files, parts of pre-existing data that
match the current data will be replaced.
If overwrite is False, no existing data will be overwritten or
replaced.
verbose : bool
If verbose is True, this will print a snippet of the sidecar files. If
False, no content will be printed.
Returns
-------
anat_dir : str
Path to the anatomical scan in the `bids_dir`
"""
if not has_nibabel(): # pragma: no cover
raise ImportError('This function requires nibabel.')
import nibabel as nib
if deface and (trans is None or raw is None):
raise ValueError('The raw object, trans and raw must be provided to '
'deface the T1')
# Make directory for anatomical data
anat_dir = op.join(bids_root, 'sub-{}'.format(subject))
# Session is optional
if session is not None:
anat_dir = op.join(anat_dir, 'ses-{}'.format(session))
anat_dir = op.join(anat_dir, 'anat')
if not op.exists(anat_dir):
os.makedirs(anat_dir)
# Try to read our T1 file and convert to MGH representation
if isinstance(t1w, str):
t1w = nib.load(t1w)
elif type(t1w) not in nib.all_image_classes:
raise ValueError('`t1w` must be a path to a T1 weighted MRI data file '
', or a nibabel image object, but it is of type '
'"{}"'.format(type(t1w)))
t1w = nib.Nifti1Image(t1w.dataobj, t1w.affine)
# XYZT_UNITS = NIFT_UNITS_MM (10 in binary or 2 in decimal)
# seems to be the default for Nifti files
# https://nifti.nimh.nih.gov/nifti-1/documentation/nifti1fields/nifti1fields_pages/xyzt_units.html
if t1w.header['xyzt_units'] == 0:
t1w.header['xyzt_units'] = np.array(10, dtype='uint8')
# Now give the NIfTI file a BIDS name and write it to the BIDS location
t1w_basename = make_bids_basename(subject=subject, session=session,
acquisition=acquisition, prefix=anat_dir,
suffix='T1w.nii.gz')
# Check if we have necessary conditions for writing a sidecar JSON
if trans is not None:
# get trans and ensure it is from head to MRI
trans, _ = _get_trans(trans, fro='head', to='mri')
if not isinstance(raw, BaseRaw):
raise ValueError('`raw` must be specified if `trans` is not None')
# Prepare to write the sidecar JSON
# extract MEG landmarks
coords_dict = _extract_landmarks(raw.info['dig'])
meg_landmarks = np.asarray((coords_dict['LPA'],
coords_dict['NAS'],
coords_dict['RPA']))
# Transform MEG landmarks into MRI space, adjust units by * 1e3
mri_landmarks = apply_trans(trans, meg_landmarks, move=True) * 1e3
# Get landmarks in voxel space, using the mgh version of our T1 data
t1_mgh = nib.MGHImage(t1w.dataobj, t1w.affine)
vox2ras_tkr = t1_mgh.header.get_vox2ras_tkr()
ras2vox_tkr = np.linalg.inv(vox2ras_tkr)
mri_landmarks = apply_trans(ras2vox_tkr, mri_landmarks) # in vox
# Write sidecar.json
t1w_json = dict()
t1w_json['AnatomicalLandmarkCoordinates'] = \
{'LPA': list(mri_landmarks[0, :]),
'NAS': list(mri_landmarks[1, :]),
'RPA': list(mri_landmarks[2, :])}
fname = t1w_basename.replace('.nii.gz', '.json')
if op.isfile(fname) and not overwrite:
raise IOError('Wanted to write a file but it already exists and '
'`overwrite` is set to False. File: "{}"'
.format(fname))
_write_json(fname, t1w_json, overwrite, verbose)
if deface:
t1w = _deface(t1w, mri_landmarks, deface, trans, raw)
# Save anatomical data
if op.exists(t1w_basename):
if overwrite:
os.remove(t1w_basename)
else:
raise IOError('Wanted to write a file but it already exists and '
'`overwrite` is set to False. File: "{}"'
.format(t1w_basename))
nib.save(t1w, t1w_basename)
return anat_dir
def _write_dig_bids(bids_path,
raw,
montage=None,
acpc_aligned=False,
overwrite=False):
"""Write BIDS formatted DigMontage from Raw instance.
Handles coordinatesystem.json and electrodes.tsv writing
from DigMontage.
Parameters
----------
bids_path : mne_bids.BIDSPath
Path in the BIDS dataset to save the ``electrodes.tsv``
and ``coordsystem.json`` file for. ``datatype``
attribute must be ``eeg``, or ``ieeg``. For ``meg``
data, ``electrodes.tsv`` are not saved.
raw : mne.io.Raw
The data as MNE-Python Raw object.
montage : mne.channels.DigMontage | None
The montage to use rather than the one in ``raw`` if it
must be transformed from the "head" coordinate frame.
acpc_aligned : bool
Whether "mri" space is aligned to ACPC.
overwrite : bool
Whether to overwrite the existing file.
Defaults to False.
"""
# write electrodes data for iEEG and EEG
unit = "m" # defaults to meters
if montage is None:
montage = raw.get_montage()
else:
# prevent transformation back to "head", only should be used
# in this specific circumstance
if bids_path.datatype == 'ieeg':
montage.remove_fiducials()
raw.set_montage(montage)
# get coordinate frame from digMontage
digpoint = montage.dig[0]
if any(digpoint['coord_frame'] != _digpoint['coord_frame']
for _digpoint in montage.dig):
warn("Not all digpoints have the same coordinate frame. "
"Skipping electrodes.tsv writing...")
return
# get the accepted mne-python coordinate frames
coord_frame_int = int(digpoint['coord_frame'])
mne_coord_frame = MNE_FRAME_TO_STR.get(coord_frame_int, None)
coord_frame = MNE_TO_BIDS_FRAMES.get(mne_coord_frame, None)
if bids_path.datatype == 'ieeg' and mne_coord_frame == 'mri':
if acpc_aligned:
coord_frame = 'ACPC'
else:
raise RuntimeError(
'`acpc_aligned` is False, if your T1 is not aligned '
'to ACPC and the coordinates are in fact in ACPC '
'space there will be no way to relate the coordinates '
'to the T1. If the T1 is ACPC-aligned, use '
'`acpc_aligned=True`')
# create electrodes/coordsystem files using a subset of entities
# that are specified for these files in the specification
coord_file_entities = {
'root': bids_path.root,
'datatype': bids_path.datatype,
'subject': bids_path.subject,
'session': bids_path.session,
'acquisition': bids_path.acquisition,
'space': bids_path.space
}
datatype = bids_path.datatype
electrodes_path = BIDSPath(**coord_file_entities,
suffix='electrodes',
extension='.tsv')
coordsystem_path = BIDSPath(**coord_file_entities,
suffix='coordsystem',
extension='.json')
logger.info(f'Writing electrodes file to... {electrodes_path}')
logger.info(f'Writing coordsytem file to... {coordsystem_path}')
if datatype == 'ieeg':
if coord_frame is not None:
# XXX: To improve when mne-python allows coord_frame='unknown'
# coordinate frame is either
coordsystem_path.update(space=coord_frame)
electrodes_path.update(space=coord_frame)
# Now write the data to the elec coords and the coordsystem
_write_electrodes_tsv(raw, electrodes_path, datatype, overwrite)
_write_coordsystem_json(raw=raw,
unit=unit,
hpi_coord_system='n/a',
sensor_coord_system=(coord_frame,
mne_coord_frame),
fname=coordsystem_path,
datatype=datatype,
overwrite=overwrite)
else:
# default coordinate frame to mri if not available
warn("Coordinate frame of iEEG coords missing/unknown "
"for {}. Skipping reading "
"in of montage...".format(electrodes_path))
elif datatype == 'eeg':
# We only write EEG electrodes.tsv and coordsystem.json
# if we have LPA, RPA, and NAS available to rescale to a known
# coordinate system frame
coords = _extract_landmarks(raw.info['dig'])
landmarks = set(['RPA', 'NAS', 'LPA']) == set(list(coords.keys()))
# XXX: to be improved to allow rescaling if landmarks are present
# mne-python automatically converts unknown coord frame to head
if coord_frame_int == FIFF.FIFFV_COORD_HEAD and landmarks:
# Now write the data
_write_electrodes_tsv(raw, electrodes_path, datatype, overwrite)
_write_coordsystem_json(raw=raw,
unit='m',
hpi_coord_system='n/a',
sensor_coord_system='CapTrak',
fname=coordsystem_path,
datatype=datatype,
overwrite=overwrite)
else:
warn("Skipping EEG electrodes.tsv... "
"Setting montage not possible if anatomical "
"landmarks (NAS, LPA, RPA) are missing, "
"and coord_frame is not 'head'.")
def _write_dig_bids(electrodes_fname,
coordsystem_fname,
data_path,
raw,
kind,
overwrite=False,
verbose=True):
"""Write BIDS formatted DigMontage from Raw instance.
Handles coordinatesystem.json and electrodes.tsv writing
from DigMontage.
Parameters
----------
electrodes_fname : str
Filename to save the electrodes.tsv to.
coordsystem_fname : str
Filename to save the coordsystem.json to.
data_path : str | pathlib.Path
Path to the data directory
raw : instance of Raw
The data as MNE-Python Raw object.
kind : str
Type of the data as in ALLOWED_KINDS.
overwrite : bool
Whether to overwrite the existing file.
Defaults to False.
verbose : bool
Set verbose output to true or false.
"""
# write electrodes data for iEEG and EEG
unit = "m" # defaults to meters
params = _parse_bids_filename(electrodes_fname, verbose)
subject_id = params['sub']
session_id = params['ses']
acquisition = params['acq']
# get coordinate frame from digMontage
digpoint = raw.info['dig'][0]
if any(digpoint['coord_frame'] != _digpoint['coord_frame']
for _digpoint in raw.info['dig']):
warn("Not all digpoints have the same coordinate frame. "
"Skipping electrodes.tsv writing...")
return
# get the accepted mne-python coordinate frames
coord_frame_int = int(digpoint['coord_frame'])
mne_coord_frame = MNE_FRAME_TO_STR.get(coord_frame_int, None)
coord_frame = MNE_TO_BIDS_FRAMES.get(mne_coord_frame, None)
if verbose:
print("Writing electrodes file to... ", electrodes_fname)
print("Writing coordsytem file to... ", coordsystem_fname)
if kind == "ieeg":
if coord_frame is not None:
# XXX: To improve when mne-python allows coord_frame='unknown'
if coord_frame not in BIDS_IEEG_COORDINATE_FRAMES:
coordsystem_fname = make_bids_basename(
subject=subject_id,
session=session_id,
acquisition=acquisition,
space=coord_frame,
suffix='coordsystem.json',
prefix=data_path)
electrodes_fname = make_bids_basename(subject=subject_id,
session=session_id,
acquisition=acquisition,
space=coord_frame,
suffix='electrodes.tsv',
prefix=data_path)
coord_frame = 'Other'
# Now write the data to the elec coords and the coordsystem
_electrodes_tsv(raw, electrodes_fname, kind, overwrite, verbose)
_coordsystem_json(raw, unit, 'n/a', coord_frame, coordsystem_fname,
kind, overwrite, verbose)
else:
# default coordinate frame to mri if not available
warn("Coordinate frame of iEEG coords missing/unknown "
"for {}. Skipping reading "
"in of montage...".format(electrodes_fname))
elif kind == 'eeg':
# We only write EEG electrodes.tsv and coordsystem.json
# if we have LPA, RPA, and NAS available to rescale to a known
# coordinate system frame
coords = _extract_landmarks(raw.info['dig'])
landmarks = set(['RPA', 'NAS', 'LPA']) == set(list(coords.keys()))
# XXX: to be improved to allow rescaling if landmarks are present
# mne-python automatically converts unknown coord frame to head
if coord_frame_int == FIFF.FIFFV_COORD_HEAD and landmarks:
# Now write the data
_electrodes_tsv(raw, electrodes_fname, kind, overwrite, verbose)
_coordsystem_json(raw, 'm', 'RAS', 'CapTrak', coordsystem_fname,
kind, overwrite, verbose)
else:
warn("Skipping EEG electrodes.tsv... "
"Setting montage not possible if anatomical "
"landmarks (NAS, LPA, RPA) are missing, "
"and coord_frame is not 'head'.")
