osl_ephys.source_recon.wrappers#

Wrappers for source reconstruction.

This module contains the functions callable using a ‘source_recon’ section of a config.

Functions#

`rescale_sensor_positions`(outdir, subject, rescale)	Wrapper to move sensor positions.
`extract_polhemus_from_info`(outdir, subject[, ...])	Wrapper function to extract fiducials/headshape points.
`extract_fiducials_from_fif`(args, *kwargs)	Wrapper for extract_polhemus_from_info.
`remove_stray_headshape_points`(outdir, subject[, nose])	Remove stray headshape points.
`save_mni_fiducials`(outdir, subject, filepath)	Wrapper to save MNI fiducials.
`extract_polhemus_from_pos`(outdir, subject, filepath)	Wrapper to save polhemus data from a .pos file.
`extract_polhemus_from_elc`(outdir, subject, filepath[, ...])	Wrapper to save polhemus data from an .elc file.
`compute_surfaces`(outdir, subject, smri_file[, ...])	Wrapper for computing surfaces.
`make_watershed_bem`(outdir, subject[, overwrite, reportdir])	Wrapper for making the watershed BEM.
`coregister`(outdir, subject[, preproc_file, ...])	Wrapper for coregistration.
`forward_model`(outdir, subject[, smri_file, ...])	Wrapper for computing the forward model.
`beamform`(outdir, subject, preproc_file, epoch_file, ...)	Wrapper function for beamforming.
`minimum_norm`(outdir, subject, preproc_file, ...[, ...])	Wrapper function for MNE source localization.
`parcellate`(outdir, subject, preproc_file, epoch_file, ...)	Wrapper function for parcellation.
`beamform_and_parcellate`(outdir, subject, preproc_file, ...)	Wrapper function for beamforming and parcellation.
`minimum_norm_and_parcellate`(outdir, subject, ...[, ...])	Wrapper function for minimum_norm and parcellation.
`find_template_subject`(outdir, subjects[, ...])	Function to find a good subject to align other subjects to in the sign flipping.
`fix_sign_ambiguity`(outdir, subject, preproc_file, ...)	Wrapper function for fixing the dipole sign ambiguity.
`extract_rhino_files`(outdir, subject, old_outdir)	Wrapper function for extracting RHINO files from a previous run.

Module Contents#

osl_ephys.source_recon.wrappers.rescale_sensor_positions(outdir, subject, rescale)[source]#

Wrapper to move sensor positions.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
rescale (list, optional) – List containing scaling factors for the x,y,z coordinates of the headshape points and fiducials: [xscale, yscale, zscale].

osl_ephys.source_recon.wrappers.extract_polhemus_from_info(outdir, subject, include_eeg_as_headshape=False, include_hpi_as_headshape=True, rescale=None, preproc_file=None, epoch_file=None)[source]#

Wrapper function to extract fiducials/headshape points.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
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?
rescale (list, optional) – List containing scaling factors for the x,y,z coordinates of the headshape points and fiducials: [xscale, yscale, zscale].
preproc_file (str, optional) – Path to the preprocessed fif file.
epoch_file (str, optional) – Path to the preprocessed fif file.

osl_ephys.source_recon.wrappers.extract_fiducials_from_fif(*args, **kwargs)[source]#: Wrapper for extract_polhemus_from_info.

osl_ephys.source_recon.wrappers.remove_stray_headshape_points(outdir, subject, nose=True)[source]#

Remove stray headshape points.

This function removes headshape points on the nose, neck and far from the head.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
noise (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.

osl_ephys.source_recon.wrappers.save_mni_fiducials(outdir, subject, filepath)[source]#

Wrapper to save MNI fiducials.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
filepath (str) –
Full path to the text file containing the fiducials.

Any reference to ‘{subject}’ (or ‘{0}’) is replaced by the subject ID. E.g. ‘data/fiducials/{subject}_smri_fids.txt’ with subject=’sub-001’ will become ‘data/fiducials/sub-001_smri_fids.txt’.

The file must be in MNI space with the following format:

nas -0.5 77.5 -32.6 lpa -74.4 -20.0 -27.2 rpa 75.4 -21.1 -21.9

Note, the first column (fiducial naming) is ignored but the rows must be in the above order, i.e. be (nasion, left, right).

The order of the coordinates is the same as given in FSLeyes.

osl_ephys.source_recon.wrappers.extract_polhemus_from_pos(outdir, subject, filepath)[source]#

Wrapper to save polhemus data from a .pos file.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
filepath (str) – Full path to the pos file for this subject. Any reference to ‘{subject}’ (or ‘{0}’) is replaced by the subject ID. E.g. ‘data/{subject}/meg/{subject}_headshape.pos’ with subject=’sub-001’ becomes ‘data/sub-001/meg/sub-001_headshape.pos’.

osl_ephys.source_recon.wrappers.extract_polhemus_from_elc(outdir, subject, filepath, remove_headshape_near_nose=False)[source]#

Wrapper to save polhemus data from an .elc file.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
filepath (str) – Full path to the elc file for this subject. Any reference to ‘{subject}’ (or ‘{0}’) is replaced by the subject ID. E.g. ‘data/{subject}/meg/{subject}_headshape.elc’ with subject=’sub-001’ becomes ‘data/sub-001/meg/sub-001_headshape.elc’.
remove_headshape_near_nose (bool, optional) – Should we remove any headshape points near the nose?

osl_ephys.source_recon.wrappers.compute_surfaces(outdir, subject, smri_file, include_nose=True, cleanup_files=True, recompute_surfaces=False, do_mri2mniaxes_xform=True, use_qform=False, reportdir=None)[source]#

Wrapper for computing surfaces.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
smri_file (str) – Path to the T1 weighted structural MRI file to use in source reconstruction.
include_nose (bool, optional) – Should we include the nose when we’re extracting the surfaces?
cleanup_files (bool, optional) – Specifies whether to cleanup intermediate files in the surfaces directory.
recompute_surfaces (bool, optional) – Specifies whether or not to run compute_surfaces, if the passed in options have already been run.
do_mri2mniaxes_xform (bool, optional) – Specifies whether to do step 1) of compute_surfaces, i.e. transform sMRI to be aligned with the MNI axes. Sometimes needed when the sMRI goes out of the MNI FOV after step 1).
use_qform (bool, optional) – Should we replace the sform with the qform? Useful if the sform code is incompatible with OSL, but the qform is compatible.
reportdir (str, optional) – Path to report directory.

osl_ephys.source_recon.wrappers.make_watershed_bem(outdir, subject, overwrite=False, reportdir=None)[source]#

Wrapper for making the watershed BEM.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
reportdir (str, optional) – Path to report directory.

osl_ephys.source_recon.wrappers.coregister(outdir, subject, preproc_file=None, epoch_file=None, surface_extraction_method='fsl', use_nose=True, use_headshape=True, already_coregistered=False, allow_smri_scaling=False, n_init=None, reportdir=None, **kwargs)[source]#

Wrapper for coregistration.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
preproc_file (str, optional) – Path to the preprocessed fif file.
epoch_file (str, optional) – Path to the preprocessed epochs fif file.
surface_extraction_method (str, optional) – Method used to extract the surfaces. Can be ‘fsl’ or ‘freesurfer’.
use_nose (bool, optional) – Should we use the nose in the coregistration?
use_headshape (bool, optional) – Should we use the headshape points in the coregistration?
already_coregistered (bool, optional) – Indicates that the data is already coregistered.
allow_smri_scaling (bool, str, optional) – 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. if in surface_extraction_method=’freesurfer’, this can be ‘uniform’ or ‘3-axis’.
n_init (int, optional) – Number of initialisations for coregistration. Different defaults for surface_extraction_method=’fsl’ and surface_extraction_method=’freesurfer’
reportdir (str, optional) – Path to report directory.

osl_ephys.source_recon.wrappers.forward_model(outdir, subject, smri_file=None, surface_extraction_method='fsl', gridstep=8, model='Single Layer', source_space='volumetric', eeg=False, reportdir=None, **kwargs)[source]#

Wrapper for computing the forward model.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
smri_file (str, optional) – Path to the T1 weighted structural MRI file to use in source reconstruction. Only required if using freesurfer and a volumentric source space.
surface_extraction_method (str, optional) – Method used to extract the surfaces. Can be ‘fsl’ or ‘freesurfer’.
gridstep (int, optional) – A grid will be constructed with the spacing given by gridstep in mm, generating a volume source space.
model (str, optional) – Type of forward model to use. Can be ‘Single Layer’ or ‘Triple Layer’, where: ‘Single Layer’ use a single layer (brain/cortex) ‘Triple Layer’ uses three layers (scalp, inner skull, brain/cortex)
source_space (str, optional) – Are we using volumetric, or surface based forward model? Can be ‘volumetric’ (or ‘vol’) or ‘surface’ (or ‘surf’). Currently, `surface_extraction_method=’fsl’ is only supported for volumetric forward models.
eeg (bool, optional) – Are we using EEG channels in the source reconstruction?
reportdir (str, optional) – Path to report directory.

osl_ephys.source_recon.wrappers.beamform(outdir, subject, preproc_file, epoch_file, chantypes, rank, freq_range=None, weight_norm='nai', pick_ori='max-power-pre-weight-norm', reg=0, reportdir=None)[source]#

Wrapper function for beamforming.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
preproc_file (str) – Path to the preprocessed fif file.
epoch_file (str) – Path to epoched preprocessed fif file.
chantypes (str or list of str) – Channel types to use in beamforming.
rank (dict) – Keys should be the channel types and the value should be the rank to use.
freq_range (list, optional) – Lower and upper band to bandpass filter before beamforming. If None, no filtering is done.
weight_norm (str, optional) – Beamformer weight normalisation.
pick_ori (str, optional) – Orientation of the dipoles.
reg (float, optional) – The regularization for the whitened data covariance.
reportdir (str, optional) – Path to report directory

osl_ephys.source_recon.wrappers.minimum_norm(outdir, subject, preproc_file, epoch_file, chantypes, rank, surface_extraction_method='fsl', depth=0.8, loose='auto', lambda2=1.0 / 9, pick_ori='pca', freq_range=None, reportdir=None, **kwargs)[source]#

Wrapper function for MNE source localization.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
preproc_file (str) – Path to the preprocessed fif file.
epoch_file (str) – Path to epoched preprocessed fif file.
chantypes (list) – List of channel types to include.
rank (int) – Rank of the noise covariance matrix.
surface_extraction_method (str) – Method used to extract the surfaces. Can be ‘fsl’ or ‘freesurfer’.
depth (float, optional) – Depth weighting.
loose (float, optional) – Loose orientation constraint.
lambda2 (float) – Regularization parameter for the minimum norm estimate. Use 1/9 for MEG, 1 for EEG.
pick_ori (str) – Orientation of the dipoles.
freq_range (list, optional) – Lower and upper band to bandpass filter before source estimation. If None, no filtering is done.
reportdir (str, optional) – Path to report directory.

osl_ephys.source_recon.wrappers.parcellate(outdir, subject, preproc_file, epoch_file, parcellation_file, method, orthogonalisation, source_space, surface_extraction_method='fsl', source_method='lcmv', spatial_resolution=None, reference_brain=None, voxel_trans='ztrans', extra_chans='stim', neighbour_distance=None, reportdir=None, **kwargs)[source]#

Wrapper function for parcellation.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
preproc_file (str) – Path to the preprocessed fif file.
epoch_file (str) – Path to epoched preprocessed fif file.
parcellation_file (str) – Path to the parcellation file to use.
method (str) – Method to use in the parcellation.
orthogonalisation (str, None) – Options are ‘symmetric’, ‘local’, None. If ‘local’, neighbour_distance must be specified.
source_space (str) – Source model to use. Can be ‘volumetric’ (/’vol’) or ‘surface’ (/’surf’).
surface_extraction_method (str) – Method used to extract the surfaces. Can be ‘fsl’ or ‘freesurfer’.
source_method (str, optional) – Method used for source reconstruction. Can be ‘lcmv’ or one of the MNE methods (‘mne’, ‘dspm’, ‘sloreta’, ‘eloreta’).
spatial_resolution (int, optional) – Resolution for beamforming to use for the reference brain in mm (must be an integer, or will be cast to nearest int). If None, then the gridstep used in coreg_filenames[‘forward_model_file’] is used.
reference_brain (str, optional) – Default depends on surface_extraction_method (fsl or freesurfer) and source_method (lcmv or mne). If surface_extraction_method=’fsl’, defaults to ‘mni’. Alternatives: ‘mri’ or ‘unscaled_mri’. If surface_extraction_method=’freesurfer’, defaults to ‘fsaverage’. Alternatives: ‘mri’.
voxel_trans (str, optional) – Should we standardise (‘ztrans’) or de-mean (‘demean’) the voxel time courses? If None, no normalisation is applied.
extra_chans (str or list of str, optional) – Extra channels to include in the parc-raw.fif file. Defaults to ‘stim’. Stim channels are always added to parc-raw.fif in addition to extra_chans.
neighbour_distance (float, optional) – Distance in mm between parcel centers to consider neighbours for orthogonalisation=’local’.
reportdir (str, optional) – Path to report directory.

osl_ephys.source_recon.wrappers.beamform_and_parcellate(outdir, subject, preproc_file, epoch_file, chantypes, rank, parcellation_file, method, orthogonalisation, freq_range=None, weight_norm='nai', pick_ori='max-power-pre-weight-norm', reg=0, spatial_resolution=None, reference_brain='mni', extra_chans='stim', neighbour_distance=None, reportdir=None)[source]#

Wrapper function for beamforming and parcellation.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
preproc_file (str) – Path to the preprocessed fif file.
epoch_file (str) – Path to epoched preprocessed fif file.
chantypes (str or list of str) – Channel types to use in beamforming.
rank (dict) – Keys should be the channel types and the value should be the rank to use.
parcellation_file (str) – Path to the parcellation file to use.
method (str) – Method to use in the parcellation.
orthogonalisation (str, None) – Options are ‘symmetric’, ‘local’, None. If ‘local’, neighbour_distance must be specified.
freq_range (list, optional) – Lower and upper band to bandpass filter before beamforming. If None, no filtering is done.
weight_norm (str, optional) – Beamformer weight normalisation.
pick_ori (str, optional) – Orientation of the dipoles.
reg (float, optional) – The regularization for the whitened data covariance.
spatial_resolution (int, optional) – Resolution for beamforming to use for the reference brain in mm (must be an integer, or will be cast to nearest int). If None, then the gridstep used in coreg_filenames[‘forward_model_file’] is used.
reference_brain (str, optional) – ‘mni’ indicates that the reference_brain is the stdbrain in MNI space. ‘mri’ indicates that the reference_brain is the subject’s sMRI in the scaled native/mri space. ‘unscaled_mri’ indicates that the reference_brain is the subject’s sMRI in unscaled native/mri space. Note that Scaled/unscaled relates to the allow_smri_scaling option in coreg. If allow_scaling was False, then the unscaled MRI will be the same as the scaled MRI.
extra_chans (str or list of str, optional) – Extra channels to include in the parc-raw.fif file. Defaults to ‘stim’. Stim channels are always added to parc-raw.fif in addition to extra_chans.
neighbour_distance (float, optional) – Distance in mm between parcel centers to consider neighbours for orthogonalisation=’local’.
reportdir (str, optional) – Path to report directory.

osl_ephys.source_recon.wrappers.minimum_norm_and_parcellate(outdir, subject, preproc_file, epoch_file, source_method, source_space, chantypes, rank, method, parcellation_file, orthogonalisation, surface_extraction_method='fsl', depth=0.8, loose='auto', lambda2=1.0 / 9, pick_ori='pca', freq_range=None, spatial_resolution=None, reference_brain=None, voxel_trans='ztrans', extra_chans='stim', neighbour_distance=None, reportdir=None)[source]#

Wrapper function for minimum_norm and parcellation.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
preproc_file (str) – Path to the preprocessed fif file.
epoch_file (str) – Path to epoched preprocessed fif file.
source_method (str) – Method to use for inverse modelling (e.g., MNE, eLORETA).
source_space (str) – Source model to use (e.g., volumetric, surface).
chantypes (list) – List of channel types to include.
rank (int) – Rank of the noise covariance matrix.
method (str) – Method to use in the parcellation.
parcellation_file (str) – Path to the parcellation file to use.
orthogonalisation (str, None) – Options are ‘symmetric’, ‘local’, None. If ‘local’, neighbour_distance must be specified.
surface_extraction_method (str, optional) – Method used for surface extraction. Can be ‘freesurfer’ or ‘fsl’.
depth (float, optional) – Depth weighting.
loose (float, optional) – Loose orientation constraint.
lambda2 (float) – Regularization parameter for the minimum norm estimate. Use 1/9 for MEG, 1 for EEG.
pick_ori (str) – Orientation of the dipoles.
freq_range (list, optional) – Lower and upper band to bandpass filter before beamforming. If None, no filtering is done.
spatial_resolution (int, optional) – Resolution for beamforming to use for the reference brain in mm (must be an integer, or will be cast to nearest int). If None, then the gridstep used in coreg_filenames[‘forward_model_file’] is used.
reference_brain (str, optional) – Default depends on surface_extraction_method. If surface_extraction_method=’fsl’, defaults to ‘mni’. Alternatives: ‘mri’ or ‘unscaled_mri’. If surface_extraction_method=’freesurfer’, defaults to ‘fsaverage’. Alternatives: ‘mri’.
voxel_trans (str, optional) – Should we standardise (‘ztrans’) or de-mean (‘demean’) the voxel time courses? If None, no normalisation is applied.
extra_chans (str or list of str, optional) – Extra channels to include in the parc-raw.fif file. Defaults to ‘stim’. Stim channels are always added to parc-raw.fif in addition to extra_chans.
neighbour_distance (float, optional) – Distance in mm between parcel centers to consider neighbours for orthogonalisation=’local’.
reportdir (str, optional) – Path to report directory.

osl_ephys.source_recon.wrappers.find_template_subject(outdir, subjects, n_embeddings=1, standardize=True, epoched=False, source_method='lcmv')[source]#

Function to find a good subject to align other subjects to in the sign flipping.

Note, this function expects parcellated data to exist in the following location: outdir//parc/parc-.fif, the * here represents subject directories or ‘raw’ vs ‘epo’.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subjects (str) – Subjects to include.
n_embeddings (int, optional) – Number of time-delay embeddings that we will use (if we are doing any).
standardize (bool, optional) – Should we standardize (z-transform) the data before sign flipping?
epoched (bool, optional) – Are we performing sign flipping on parc-raw.fif (epoched=False) or parc-epo.fif files (epoched=True)?
source_method (str, optional) – Method to used for inverse modelling (e.g., LCMV, MNE, eLORETA).

Returns:

template – Template subject.

Return type:

str

osl_ephys.source_recon.wrappers.fix_sign_ambiguity(outdir, subject, preproc_file, template, n_embeddings, standardize, n_init, n_iter, max_flips, epoched=False, source_method='lcmv', reportdir=None)[source]#

Wrapper function for fixing the dipole sign ambiguity.

Parameters:

outdir (str) – Path to where to output the source reconstruction files.
subject (str) – Subject name/id.
preproc_file (str) – Path to the preprocessed fif file.
template (str) – Template subject.
n_embeddings (int) – Number of time-delay embeddings that we will use (if we are doing any).
standardize (bool) – Should we standardize (z-transform) the data before sign flipping?
n_init (int) – Number of initializations.
n_iter (int) – Number of sign flipping iterations per subject to perform.
max_flips (int) – Maximum number of channels to flip in an iteration.
epoched (bool, optional) – Are we performing sign flipping on parc-raw.fif (epoched=False) or parc-epo.fif files (epoched=True)?
source_method (str, optional) – Method to used for inverse modelling (e.g., LCMV, MNE, eLORETA).
reportdir (str, optional) – Path to report directory.

osl_ephys.source_recon.wrappers.extract_rhino_files(outdir, subject, old_outdir)[source]#

Wrapper function for extracting RHINO files from a previous run.

Parameters:

outdir (str) – Path to the NEW source reconstruction directory.
subject (str) – Subject name/id.
old_outdir (str) – OLD source reconstruction directory to copy RHINO files to.