osl_dynamics.meeg.rhino#

RHINO functions.

Functions#

scale_surfaces_to_headshape(preproc_file, ...[, n_init])

Scale surfaces to match headshape points.

extract_surfaces(mri_file, outdir[, include_nose, ...])

Extract surfaces.

plot_surfaces(outdir, id[, include_nose])

Plot a structural MRI and extracted surfaces.

extract_fiducials_and_headshape_from_fif(fns[, ...])

Extract headshape points and fiducials from FIF info.

extract_fiducials_and_headshape_from_pos(fns)

Saves fiducials/headshape from a pos file.

extract_fiducials_and_headshape_from_elc(fns[, ...])

Extract fiducials and headshape points from an ELC file.

remove_stray_headshape_points(fns[, nose])

Remove stray headshape points.

save_coregistration_files(fns)

Data is already coregistered, just save the files needed for RHINO.

coregister_head_and_mri(fns[, use_headshape, ...])

Coregister HEAD (polhemus) and MRI space.

plot_coregistration(fns[, display_outskin, ...])

Plot coregistration.

forward_model(fns[, model, gridstep, mindist, ...])

Compute forward model.

Module Contents#

osl_dynamics.meeg.rhino.scale_surfaces_to_headshape(preproc_file, surfaces_dir, outdir, n_init=10)[source]#

Scale surfaces to match headshape points.

Computes an affine transform that scales an existing set of surfaces (from extract_surfaces or the bundled MNI152 surfaces) to match the headshape digitisation points in a FIF file. The scaled MRI and surfaces are written to outdir.

This is useful when no individual structural MRI is available (e.g., OPM recordings with EinScan headshape).

The method:

  1. Aligns the headshape to the template scalp surface using fiducials and ICP.

  2. Computes an affine transform (with anisotropic scaling) from nearest-neighbour correspondences between the aligned surfaces.

  3. Applies the transform to the MRI and surfaces.

Parameters:

  • preproc_file (str) – Path to preprocessed FIF file containing headshape points in info['dig'].

  • surfaces_dir (str) – Path to a directory containing extracted surfaces (from extract_surfaces). For the default MNI152 brain, use osl_dynamics.files.mni152_surfaces.directory.

  • outdir (str) – Output directory for the scaled MRI and surfaces. Pass this as surfaces_dir when creating OSLFilenames.

  • n_init (int, optional) – Number of random initialisations for ICP alignment.

Returns:

outdir – Path to the output directory containing the scaled MRI and surfaces.

Return type:

str

osl_dynamics.meeg.rhino.extract_surfaces(mri_file, outdir, include_nose=True, do_mri2mniaxes_xform=True, bet_fval=None, show=False)[source]#

Extract surfaces.

Extracts inner skull, outer skin (scalp) and brain surfaces from passed in mri_file, which is assumed to be a T1, using FSL. Assumes that the MRI file has a valid sform.

In more detail: 1) Transform MRI to be aligned with the MNI axes so that BET works well 2) Use bet to skull strip MRI so that flirt works well 3) Use flirt to register skull stripped MRI to MNI space 4) Use BET/BETSURF to get:

  1. The scalp surface (excluding nose), this gives the MRI-derived headshape points in native MRI space, which can be used in the headshape points registration later.

  2. The scalp surface (outer skin), inner skull and brain surface, these can be used for forward modelling later. Note that due to the unusual naming conventions used by BET: - bet_inskull_mesh_file is actually the brain surface - bet_outskull_mesh_file is actually the inner skull surface - bet_outskin_mesh_file is the outer skin/scalp surface

  1. Add nose to scalp surface (optional)

  2. Output the transform from MRI space to MNI

  3. Output surfaces in MRI space

Parameters:

  • mri_file (str) – Full path to structural MRI in NIfTI format (with .nii.gz, .nii, .hdr or .mgz extension). The sform code must be 1 (Scanner Anat) or 4 (MNI), and the sform matrix should transform from voxel indices to coordinates in mm. The sform defines the native/MRI coordinate system used throughout RHINO. The qform is ignored. You can check the sform code with fslorient -getsformcode <mri_file> and set it with fslorient -setsformcode 1 <mri_file>.

  • outdir (str) – Output directory.

  • include_nose (bool, optional) – Specifies whether to add the nose to the outer skin (scalp) surface. This can help RHINO’s coregistration to work better, assuming that there are headshape points that also include the nose. Requires the structural MRI to have a FOV that includes the nose!

  • do_mri2mniaxes_xform (bool, optional) – Specifies whether to do step (1) above, i.e. transform MRI to be aligned with the MNI axes. Sometimes needed when the MRI goes out of the MNI FOV after step (1).

  • bet_fval (float, optional) – Fractional intensity threshold for FSL’s BET. Default is None, which uses BET’s default (0.5). Higher values (e.g. 0.6-0.7) give more aggressive skull stripping, which can help when the inner skull surface includes non-brain tissue.

  • show (bool, optional) – Whether to display the surface plots interactively. Default is False (suitable for batch processing).

Return type:

None

osl_dynamics.meeg.rhino.plot_surfaces(outdir, id, include_nose=True)[source]#

Plot a structural MRI and extracted surfaces.

Parameters:

  • outdir (str) – Output directory.

  • id (str) – Identifier for the subject/session subdirectory in the output directory.

  • include_nose (bool, optional) – Should we also plot the outskin surface including the nose?

Return type:

None

osl_dynamics.meeg.rhino.extract_fiducials_and_headshape_from_fif(fns, include_eeg_as_headshape=False, include_hpi_as_headshape=True)[source]#

Extract headshape points and fiducials from FIF info.

Extract (polhemus) fiducials and headshape points from MNE raw.info and write them out in the required file format for RHINO (in HEAD space in mm).

Should only be used with MNE-derived .fif files that have the expected digitised points held in info[‘dig’] of fif_file.

Parameters:

  • fns (OSLFilenames) – Container for OSL filenames.

  • include_eeg_as_headshape (bool, optional) – Should we include EEG locations as headshape points?

  • include_hpi_as_headshape (bool, optional) – Should we include HPI locations as headshape points?

Return type:

None

osl_dynamics.meeg.rhino.extract_fiducials_and_headshape_from_pos(fns)[source]#

Saves fiducials/headshape from a pos file.

Parameters:

fns (OSLFilenames) – Container for OSL filenames.

Return type:

None

osl_dynamics.meeg.rhino.extract_fiducials_and_headshape_from_elc(fns, remove_nose=True)[source]#

Extract fiducials and headshape points from an ELC file.

Reads fiducial locations (nasion, LPA, RPA) and headshape points from an ELC file (ANT Neuro) and saves them in the RHINO file format.

The ELC file is expected to contain a Positions section with three fiducial rows (nasion, LPA, RPA) and a HeadShapePoints section with 3D coordinates. All values are assumed to be in mm.

Parameters:

  • fns (OSLFilenames) – Container for OSL filenames. fns.elc_file must be set.

  • remove_nose (bool, optional) – Remove headshape points on the nose? A point is considered to be on the nose if it is anterior to both LPA and RPA and inferior to the nasion.

Return type:

None

osl_dynamics.meeg.rhino.remove_stray_headshape_points(fns, nose=True)[source]#

Remove stray headshape points.

Removes headshape points near the nose, on the neck or far away from the head. The filtering is done in a coordinate system derived from the fiducial points (nasion, LPA, RPA), so it works regardless of the original coordinate convention (e.g. Elekta/FIF or CTF/.pos).

The fiducial-derived axes are:

  • left-right: LPA to RPA direction.

  • anterior: perpendicular to the left-right axis, pointing towards the nasion.

  • superior: cross product of the above two axes.

Parameters:

  • fns (OSLFilenames) – Container for OSL filenames.

  • nose (bool, optional) – Should we remove headshape points near the nose? Useful to remove these if we have defaced structurals or aren’t extracting the nose from the structural.

Return type:

None

osl_dynamics.meeg.rhino.save_coregistration_files(fns)[source]#

Data is already coregistered, just save the files needed for RHINO.

Assumes that the sensor locations and fiducials/headshape points (if there are any) are already in MRI space. This means that dev_head_t is identity and that dev_mri_t is identity.

Parameters:

fns (OSLFilenames) – Container for OSL filenames.

Return type:

None

osl_dynamics.meeg.rhino.coregister_head_and_mri(fns, use_headshape=True, use_nose=True, allow_mri_scaling=False, mni_fiducials=None, n_init=1, plot_type='png', show=False)[source]#

Coregister HEAD (polhemus) and MRI space.

Calculates a linear, affine transform from HEAD space to MRI space using headshape points (if use_headshape=True).

Requires rhino.extract_surfaces to have been run.

RHINO firsts registers the polhemus-derived fiducials (nasion, rpa, lpa) in HEAD space to the MRI-derived fiducials in native MRI space.

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

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

In more detail: 1) Map location of fiducials in MNI standard space brain to native MRI

space. These are then used as the location of the MRI-derived fiducials in native MRI space.

2a) We have polhemus-derived fiducials in HEAD space and MRI-derived fiducials

in native MRI space. Use these to estimate the affine xform from native MRI space to HEAD space.

2b) We can also optionally learn the best scaling to add to this affine

xform, such that the MRI-derived fiducials are scaled in size to better match the polhemus-derived fiducials. This assumes that we trust the size (e.g. in mm) of the polhemus-derived fiducials, but not the size of MRI-derived fiducials. E.g. this might be the case if we do not trust the size (e.g. in mm) of the MRI, or if we are using a template MRI that would has not come from this subject.

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

  2. Transform MRI-derived headshape points into HEAD space.

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

Parameters:

  • fns (OSLFilenames) – Container for OSL filenames.

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

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

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

  • mni_fiducials (list, optional) – Fiducials for the MRI in MNI space. Must be [nasion, rpa, lpa], where nasion, rpa, lpa are 3D coordinates. Defaults to [[1, 85, -41], [83, -20, -65], [-83, -20, -65]].

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

  • plot_type (str, optional) – Type of coregistration plot to save. Options are “png”, “html” or None. “png” saves static PNG images (requires a display/render window). “html” saves an interactive HTML file (works in headless environments). None skips plotting.

  • show (bool, optional) – Whether to display the coregistration plot interactively. Default is False (suitable for batch processing).

Return type:

None

osl_dynamics.meeg.rhino.plot_coregistration(fns, display_outskin=True, display_sensors=True, display_sensor_oris=True, display_fiducials=True, display_headshape_pnts=True, include_nose=True, filename=None, show=False)[source]#

Plot coregistration.

Parameters:

  • fns (OSLFilenames) – Container for OSL filenames.

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

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

  • display_sensor_oris (bool, optional) – Whether to include sensor orientations in the display.

  • display_fiducials (bool, optional) – Whether to include fiducials in the display.

  • display_headshape_pnts (bool, optional) – Whether to include headshape points in the display.

  • include_nose (bool, option) – Should we use the outskin surface with the nose?

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

  • show (bool, optional) – Should we show the plots? Only used if filename has extension ‘.png’.

Return type:

None

osl_dynamics.meeg.rhino.forward_model(fns, model='Single Layer', gridstep=8, mindist=4.0, exclude=0.0, eeg=False, meg=True, verbose=False)[source]#

Compute forward model.

Parameters:

  • fns (OSLFilenames) – Container for OSL filenames.

  • model (string, optional) –

    Options are: - ‘Single Layer’ to use single layer (brain/cortex).

    Recommended for MEG.

    • ’Triple Layer’ to three layers (scalp, inner skull, brain/cortex). Recommended for EEG.

  • gridstep (int, optional) – A grid will be constructed with the spacing given by gridstep in mm generating a volume source space.

  • mindist (float) – Exclude points closer than this distance (mm) to the bounding surface.

  • exclude (float, optional) – Exclude points closer than this distance (mm) from the center of mass of the bounding surface.

  • eeg (bool, optional) – Whether to compute forward model for EEG sensors.

  • meg (bool, optional) – Whether to compute forward model for MEG sensors.

  • verbose (bool)

Return type:

None