Coregistration, MEG to MRI

This module may be employed to coregister MEG to MRI images.

src_rec.coreg.Coreg(signal_type, rotors: ndarray = None, closest_pts_nas: ndarray = None, closest_pts_lpa: ndarray = None, closest_pts_rpa: ndarray = None, closest_pts_eeg: ndarray = None)

Container class containing the following parameters.

For EEG, a EEG cap is projected onto the skull, for MEG registration points are matched with MRI surface.

src_rec.coreg.rotors

Sequence of rotors defining rotation (3), translation (3) and scaling (3). MEG only.

Type:

np.ndarray, shape(9,)

src_rec.coreg.mri_to_meeg_trs

Full affine transformation matrix (MRI -> MEEG). MEG only.

Type:

np.ndarray, shape(4, 4)

src_rec.coreg.mri_to_meeg_tr

Rigid affine transformation matrix (MRI -> MEEG). MEG only.

Type:

np.ndarray, shape(4, 4)

src_rec.coreg.mri_to_meeg_rs

Rotation & scaling only affine transformation matrix (MRI -> MEEG). MEG only.

Type:

np.ndarray, shape(4, 4)

src_rec.coreg.mri_to_meeg_r

Rotation only affine transformation matrix (MRI -> MEEG). MEG only.

Type:

np.ndarray, shape(4, 4)

src_rec.coreg.meeg_to_mri_trs

Full affine transformation matrix (MEEG -> MRI). MEG only.

Type:

np.ndarray, shape(4, 4)

src_rec.coreg.meeg_to_mri_tr

Rigid affine transformation matrix (MEEG -> MRI). MEG only.

Type:

np.ndarray, shape(4, 4)

src_rec.coreg.meeg_to_mri_rs

Rotation & scaling only affine transformation matrix (MEEG -> MRI). MEG only.

Type:

np.ndarray, shape(4, 4)

src_rec.coreg.meeg_to_mri_r

Rotation only affine transformation matrix (MEEG -> MRI). MEG only.

Type:

np.ndarray, shape(4, 4)

src_rec.coreg.closest_pts_nas

Closest points to the nas on the MRI. EEG only.

Type:

np.ndarray, shape(3, )

src_rec.coreg.closest_pts_lpa

Closest points to the lpa on the MRI. EEG only.

Type:

np.ndarray, shape(3, )

src_rec.coreg.closest_pts_rpa

Closest points to the rpa on the MRI. EEG only.

Type:

np.ndarray, shape(3, )

src_rec.coreg.closest_pts_eeg

Closest points to the eeg positions on the MRI. EEG only.

Type:

np.ndarray, shape(eeg_ch_cnt, )

Parameters:

• signal_type (string) – Either “EEG” or “MEG.

• rotors (np.ndarray, shape(9,)) – Sequence of rotors defining rotation (3), translation (3) and scaling (3).

• closest_pts_nas (np.ndarray, shape(3, )) – Closest points to the nas on the MRI.

• closest_pts_lpa (np.ndarray, shape(3, )) – Closest points to the lpa on the MRI.

• closest_pts_rpa (np.ndarray, shape(3, )) – Closest points to the rpa on the MRI.

• closest_pts_eeg (np.ndarray, shape(eeg_ch_cnt, )) – Closest points to the eeg positions on the MRI.

src_rec.coreg.run(subj_name, anatomy_path, signal_type, use_nasion=True, rec_info=None)

Execute the complete coregistration for a specific subject.

Parameters:

• subj_name (string) – Name of the subject.

• anatomy_path (string) – Path to the anatomy folder. This folder should contain a sub-folder for each subject.

• signal_type (string) – Either “EEG” or “MEG”.

• use_nasion (bool) – Whether to use the nasion for registration, may be deacivated if the nasion is cut in the MRI.

• rec_info (string) – If signal_type is “EEG”, rec_info is the EEG setup (1020 or 1005). If signal_type is “MEG”, rec_info is the path to the FIF.file.

Returns:

result –

• coregfinnpy.src_rec.coreg.Coreg

  Container class, populed with the following items:

  • rotors : np.ndarray, shape(9,) Sequence of rotors defining rotation (3), translation (3) and scaling (3).

  • mri_to_meeg_trs : np.ndarray, shape(4, 4) Full affine transformation matrix (MRI -> MEG)

  • mri_to_meeg_tr : np.ndarray, shape(4, 4) Rigid affine transformation matrix (MRI -> MEG)

  • mri_to_meeg_rs : np.ndarray, shape(4, 4) Rotation & scaling only affine transformation matrix (MRI -> MEG)

  • mri_to_meeg_r : np.ndarray, shape(4, 4) Rotation only affine transformation matrix (MRI -> MEG)

  • meeg_to_mri_trs : np.ndarray, shape(4, 4) Full affine transformation matrix (MEG -> MRI)

  • meeg_to_mri_tr : np.ndarray, shape(4, 4) Rigid affine transformation matrix (MEG -> MRI)

  • meeg_to_mri_rs : np.ndarray, shape(4, 4) Rotation & scaling only affine transformation matrix (MEG -> MRI)

  • meeg_to_mri_r : np.ndarray, shape(4, 4) Rotation only affine transformation matrix (MEG -> MRI)

• bad_hsp_pts(list, list)

  Bad hsp points from the 1st and 2nd run of the coregistration.

Return type:

tuple of (finnpy.src_rec.coreg.Coreg, tuple of (list, list))

Raises:

AssertionError – Raised if the signal type is not either ‘EEG’ or ‘MEG’.

src_rec.coreg.plot_coregistration(coreg, signal_type, anatomy_path, subj_name, use_nasion=True, bad_hsp_pts=None, meg_data_path=None, eeg_setup='1020')

Plot the result of the coregistration from MRI to MEG using pyvista.

Parameters:

• coreg (np.ndarray, shape(4, 4)) – MEG to MRI coregistration matrix.

• signal_type (string) – “EEG” or “MEG”.

• anatomy_path (string) – Path to the anatomy folder. This folder should contain a sub-folder for each subject, to be pupulated with the corresponding structural data.

• subj_name (string) – Subject name.

• use_nasion (boolean) – Flag whether to use the nasion registration point. Not recommended for defaced patients.

• bad_hsp_pts ((list, list)) – Bad hsp points from the 1st and 2nd run of the coregistration.

• meg_data_path (string) – Path to the MEG file used in the coregistration.

• eeg_setup (string) – Setup of the EEG contacts. Defaults to 1020 system. Can be either 1020 or 1005.

Raises:

AssertionError – Raised if the signal type is not either ‘EEG’ or ‘MEG’.

src_rec.coreg._load_mri_ref_pts(anatomy_path, subj_name)

Load MEG reference points.

Parameters:

• anatomy_path (string) – Path to the anatomy folder. This folder should contain a sub-folder for each subject, to be pupulated with the corresponding structural data.

• subj_name (string) – Subject name.

Returns:

meg_pts – MRI reference points for coregistration.

Return type:

dict, (‘nasion’, ‘lpa’, ‘rpa’, ‘hsp’, ‘coord_frame’)

src_rec.coreg._format_fiducials(pre_mri_ref_pts)

Transform an mne-fiducials object into an dictionary containing the fiducials.

Parameters:

pre_mri_ref_pts (list of dict(), obtained via mne.io.read_fiducials) – MNE-formatted list of MRI fiducials.

Returns:

mri_ref_pts – MRI reference points for coregistration.

Return type:

dict(), (‘LPA’, ‘NASION’, ‘RPA’)

src_rec.coreg._load_hd_surf(anatomy_path, subj_name)

Load freesurfer extracted hd surface model vertices. If this information does not yet exists, it is created using freesurfer.

Parameters:

• anatomy_path (string) – Path to the anatomy folder. This folder should contain a sub-folder for each subject.

• subj_name (string) – Subject name.

Returns:

hd_surf_vert – High resulution surface model generated via freesurfer.

Return type:

np.ndarray, shape (n, 3)

src_rec.coreg._registrate_3d_points_restricted(src_pts, tgt_pts, weights=None, scale=False)

Registrates src points to tgt points via Horns method. The resulting 4x4 transformation matrix may contain translation, rotation, and scaling.

Parameters:

• src_pts (np.ndarray or list, shape(n, 3)) – Source points for the coregistration.

• tgt_pts (np.ndarray or list, shape(n, 3)) – Target points for the coregistration.

• weights (np.ndarray or list, shape(n)) – Weights of the individual pts.

• scale (boolean,) – Flag whether to apply uniform scaling, defaults to False

Returns:

result –

• est_rotorsnp.ndarray, shape(9,)

  Rotors of the estimated transformation.

• est_matnp.ndarray, shape(4, 4)

  Rotation matrix of the estimated transformation.

Return type:

tuple of (np.ndarray, np.ndarray)

src_rec.coreg._get_ref_ptn_cnt(meg_pts)

Get the total and hsp counts from MEG pts.

Parameters:

meg_pts (dict, ('lpa', rpa', 'nasion', 'hpi', 'hsp', 'coord_frame')) – Reference MEG points for the coregistration.

Returns:

result –

• ptn_cntint

  Number of points without hsp-points.

• hsp_cntint

  Number of hsp-points.

Return type:

tuple of (int, int)

src_rec.coreg._refine_registration(src_pts, tgt_pts, meeg_nasion_key, meeg_lpa_key, meeg_rpa_key, last_rotors, last_mat, weights, signal_type, registration_scale_type='free', coreg_thresh=0.002, max_number_of_iterations=500)

Refines an initial registration.

Parameters:

• src_pts (np.ndarray or list, shape(n1, 3)) – Source points for the coregistration.

• tgt_pts (np.ndarray or list, shape(n1, 3)) – Target points for the coregistration.

• meeg_nasion_key (string,) – Name of the nasion channel in meeg data.

• meeg_lpa_key (string,) – Name of the lpa channel in meeg data.

• meeg_rpa_key (string,) – Name of the rpa channel in meeg data.

• last_rotors (np.ndarray, shape(9,)) – Original rotor estimates.

• last_mat (np.ndarray, shape(4, 4)) – Original rotation matrix estimate.

• weights (np.ndarray or list, shape(n,)) – Weights for the coregistration.

• signal_type (string) – “EEG” or “MEG”.

• registration_scale_type (string) – If “free”, scaling is estimated across 3 axis, if “reduced”, scaling is uniform, defaults to “free”.

• coreg_thresh (float) – Coregionstration error threshold.

• max_number_of_iterations (int) – Number of iterations.

Returns:

result –

• last_rotorsnp.ndarray, shape(9,)

  Updated rotor estimates.

• last_matnp.ndarray, shape(4, 4)

  Updated rotation matrix estimate.

• tgt_pts_fullnp.ndarray, shape(m2, 3)

  Target points used for the coregistration.

• src_pts_fullnp.ndarray, shape(n2, 3)

  Source points used for the coregistration.

Return type:

tuple of (np.ndarray, np.ndarray, np.ndarray, np.ndarray)

Raises:

AssertionError – If signal type is invalid, must be either ‘EEG’ or ‘MEG’. If the registration type is invalid, has to be eitehr ‘free’ or ‘restricted’.

src_rec.coreg._rm_bad_head_shape_pts(meg_pts, mri_pts, trans_mat, distance_thresh=0.005)

Identify MEG points whose distance is too far from MRI points and remove those.

Parameters:

• meg_pts (np.ndarray or list, (m, 3)) – MEG reference points.

• mri_pts (np.ndarray or list, (n, 3)) – MRI reference points.

• trans_mat (np.ndarray, shape(4, 4)) – MEG to MRI transformation matrix.

• distance_thresh (float) – Maximum distance. Defaults to 5 mm.

Returns:

result – If there are over the threshold distances, return surviving meg pts & invalid indices. Otherwise, return only surviving meg pts. - meg_pts : np.ndarray, shape(m - x, 3)

Pruned list of MEG pts.

• surv_idxnp.ndarray, shape(x, )

  Indices of invalid points.

Return type:

tuple of (np.ndarray, np.ndarray) or np.ndarray

src_rec.coreg._registrate_3d_points_free(src_pts, tgt_pts, weights=None, initial_guess=None)

Registrate src points to tgt points via least squares minimizing. The resulting 4x4 transformation matrix may contain translation, rotation, and scaling.

Parameters:

• src_pts (np.ndarray, shape(m, 4)) – Source points for the registration.

• tgt_pts (np.ndarray, shape(n, 4)) – Target points for the registration.

• weights (np.ndarray, shape(m, 1)) – (Source) weights for the registration.

• initial_guess (np.ndarray or list or tuple or None, shape(9,)) – Initial transformation guess, defaults to None for no translation/rotation/scaling.

Returns:

result –

• est_rotorsnp.ndarray, shape(9,)

  Updated rotor estimate.

• est_matnp.ndarray, shape(4, 4)

  Updated transformation matrix.

Return type:

tuple of (np.ndarray, np.ndarray)

src_rec.coreg._translation(x, y, z)

Calculate a translation matrix from x, y, and z.

Parameters:

• x (float) – shift

• y (float) – shift

• z (float) – shift

Returns:

trans – Transformation matrix.

Return type:

np.ndarray, shape(4, 4)

src_rec.coreg._rotation(x=0, y=0, z=0)

Calculate a rotation matrix from x, y, and z.

Parameters:

• x (float) – angle

• y (float) – angle

• z (float) – angle

Returns:

trans – Transformation matrix.

Return type:

np.ndarray, shape(4, 4)

src_rec.coreg._scaling(x=1, y=1, z=1)

Calculate a scaling matrix from x, y, and z.

Parameters:

• x (float) – scale

• y (float) – scale

• z (float) – scale

Returns:

trans – Transformation matrix.

Return type:

np.ndarray, shape(4, 4)

src_rec.coreg._get_rot_and_scale_mat(rotors)

Produce a rotation and scaling matrix from rotors.

Parameters:

rotors (np.ndarray, shape(9,)) – Sequence of rotors defining rotation (3), translation (3) and scaling (3).

Returns:

trans – Transformation matrix.

Return type:

np.ndarray, shape(4, 4)

src_rec.coreg._get_trans_and_rot_mat(rotors)

Produce a rigid transformation matrix from rotors.

Parameters:

rotors (np.ndarray, shape(9,)) – Sequence of rotors defining rotation (3), translation (3) and scaling (3).

Returns:

trans – Transformation matrix.

Return type:

np.ndarray, shape(4, 4)

src_rec.coreg._get_rot_mat(rotors)

Produce a rotatio matrix from rotors.

Parameters:

rotors (np.ndarray, shape(9,)) – Sequence of rotors defining rotation (3), translation (3) and scaling (3).

Returns:

trans – Transformation matrix.

Return type:

np.ndarray, shape(4, 4)