osl_ephys.source_recon.rhino.coreg#

Registration of Headshapes Including Nose in osl-ephys (RHINO).

Functions#

get_coreg_filenames(subjects_dir, subject)

Files used in coregistration by RHINO.

coreg(fif_file, subjects_dir, subject[, ...])

Coregistration.

coreg_metrics(subjects_dir, subject)

Calculate metrics that summarise the coregistration.

coreg_display(subjects_dir, subject[, plot_type, ...])

Display coregistration.

bem_display(subjects_dir, subject[, plot_type, ...])

Displays the coregistered RHINO scalp surface and inner skull surface.

Module Contents#

osl_ephys.source_recon.rhino.coreg.get_coreg_filenames(subjects_dir, subject)[source]#

Files used in coregistration by RHINO.

Files will be in subjects_dir/subject/rhino/coreg.

Parameters:

  • subjects_dir (string) – Directory containing the subject directories.

  • subject (string) – Subject directory name to put the coregistration files in.

Returns:

filenames – A dict of files generated and used by RHINO.

Return type:

dict

osl_ephys.source_recon.rhino.coreg.coreg(fif_file, subjects_dir, subject, use_headshape=True, use_nose=True, use_dev_ctf_t=True, already_coregistered=False, allow_smri_scaling=False, n_init=1)[source]#

Coregistration.

Calculates a linear, affine transform from native sMRI space to polhemus (head) space, using headshape points that include the nose (if useheadshape = True). Requires rhino.compute_surfaces to have been run. This is based on the OSL Matlab version of RHINO. Call get_coreg_filenames(subjects_dir, subject) to get a file list of generated files. RHINO firsts registers the polhemus-derived fiducials (nasion, rpa, lpa) in polhemus space to the sMRI-derived fiducials in native sMRI space.

RHINO then refines this by making use of polhemus-derived headshape points that trace out the surface of the head (scalp), and ideally include the nose.

Finally, these polhemus-derived headshape points in polhemus space are registered to the sMRI-derived scalp surface in native sMRI space.

In more detail:

  1. Map location of fiducials in MNI standard space brain to native sMRI space. These are then used as the location of the sMRI-derived fiducials in native sMRI space.

2a) We have polhemus-derived fids in polhemus space and sMRI-derived fids in native sMRI space. Use these to estimate the affine xform from native sMRI space to polhemus

(head) space.

2b) We can also optionally learn the best scaling to add to this affine xform, such that the sMRI-derived fids are scaled in size to better match the polhemus-derived fids.

This assumes that we trust the size (e.g. in mm) of the polhemus-derived fids, but not the size of sMRI-derived fids. E.g. this might be the case if we do not trust the size (e.g. in mm) of the sMRI, or if we are using a template sMRI that would has not come from this subject.

  1. If a scaling is learnt in step 2, we apply it to sMRI, and to anything derived from sMRI.

  2. Transform sMRI-derived headshape points into polhemus space.

  3. We have the polhemus-derived headshape points in polhemus space and the sMRI-derived headshape (scalp surface) in native sMRI space. Use these to estimate the affine xform from native sMRI space using the ICP algorithm initilaised using the xform estimate in step 2.

Parameters:

  • fif_file (string) – Full path to MNE-derived fif file.

  • subjects_dir (string) – Directory to put RHINO subject dirs in. Files will be in subjects_dir/subject/coreg.

  • subject (string) – Subject name dir to put RHINO files in. Files will be in subjects_dir/subject/coreg.

  • use_headshape (bool) – Determines whether polhemus derived headshape points are used.

  • use_nose (bool) – Determines whether nose is used to aid coreg, only relevant if use_headshape=True.

  • use_dev_ctf_t (bool) – Determines whether to set dev_head_t equal to dev_ctf_t in fif_file’s info. This option is only potentially needed for fif files originating from CTF scanners. Will be ignored if dev_ctf_t does not exist in info (e.g. if the data is from a MEGIN scanner)

  • already_coregistered (bool) – Indicates that the data is already coregistered. Causes a simplified coreg to be run that assumes that device space, head space and mri space are all the same space, and that the sensor locations and polhemus points (if there are any) are already in that space. This means that dev_head_t is identity and that dev_mri_t is identity. This simplified coreg is needed to ensure that all the necessary coreg output files are created.

  • allow_smri_scaling (bool) – Indicates if we are to allow scaling of the sMRI, such that the sMRI-derived fids are scaled in size to better match the polhemus-derived fids. This assumes that we trust the size (e.g. in mm) of the polhemus-derived fids, but not the size of the sMRI-derived fids. E.g. this might be the case if we do not trust the size (e.g. in mm) of the sMRI, or if we are using a template sMRI that has not come from this subject.

  • n_init (int) – Number of initialisations for the ICP algorithm that performs coregistration.

osl_ephys.source_recon.rhino.coreg.coreg_metrics(subjects_dir, subject)[source]#

Calculate metrics that summarise the coregistration.

Parameters:

  • subjects_dir (string) – Directory containing RHINO subject directories.

  • subject (string) – Subject name directory containing RHINO files.

Returns:

fiducial_distances – Distance in cm between the polhemus and sMRI fiducials. Order is nasion, lpa, rpa.

Return type:

np.ndarray

osl_ephys.source_recon.rhino.coreg.coreg_display(subjects_dir, subject, plot_type='surf', display_outskin=True, display_outskin_with_nose=True, display_sensors=True, display_sensor_oris=True, display_fiducials=True, display_headshape_pnts=True, filename=None)[source]#

Display coregistration.

Displays the coregistered RHINO scalp surface and polhemus/sensor locations.

Display is done in MEG (device) space (in mm).

Purple dots are the polhemus derived fiducials (these only get used to initialse the coreg, if headshape points are being used).

Yellow diamonds are the MNI standard space derived fiducials (these are the ones that matter).

Parameters:

  • subjects_dir (string) – Directory to put RHINO subject dirs in. Files will be in subjects_dir/subject/rhino/coreg.

  • subject (string) – Subject name dir to put RHINO files in. Files will be in subjects_dir/subject/rhino/coreg.

  • plot_type (string) –

    Either:

    ’surf’ to do a 3D surface plot using surface meshes. ‘scatter’ to do a scatter plot using just point clouds.

  • display_outskin_with_nose (bool) – Whether to show nose with scalp surface in the display.

  • display_outskin (bool) – Whether to show scalp surface in the display.

  • display_sensors (bool) – Whether to include sensors in the display.

  • bool (display_headshape_pnts -) – Whether to include sensor orientations in the display.

  • bool – Whether to include fiducials in the display.

  • bool – Whether to include headshape points in the display.

  • filename (str) – Filename to save display to (as an interactive html). Must have extension .html.

osl_ephys.source_recon.rhino.coreg.bem_display(subjects_dir, subject, plot_type='surf', display_outskin_with_nose=True, display_sensors=False, filename=None)[source]#

Displays the coregistered RHINO scalp surface and inner skull surface.

Display is done in MEG (device) space (in mm).

Parameters:

  • subjects_dir (string) – Directory to find RHINO subject dirs in.

  • subject (string) – Subject name dir to find RHINO files in.

  • plot_type (string) –

    Either:

    ’surf’ to do a 3D surface plot using surface meshes. ‘scatter’ to do a scatter plot using just point clouds.

  • display_outskin_with_nose (bool) – Whether to include nose with scalp surface in the display.

  • display_sensors (bool) – Whether to include sensor locations in the display.

  • filename (str) – Filename to save display to (as an interactive html). Must have extension .html.