osl_ephys.source_recon.wrappers =============================== .. py:module:: osl_ephys.source_recon.wrappers .. autoapi-nested-parse:: Wrappers for source reconstruction. This module contains the functions callable using a 'source_recon' section of a config. Functions --------- .. autoapisummary:: osl_ephys.source_recon.wrappers.rescale_sensor_positions osl_ephys.source_recon.wrappers.extract_polhemus_from_info osl_ephys.source_recon.wrappers.extract_fiducials_from_fif osl_ephys.source_recon.wrappers.remove_stray_headshape_points osl_ephys.source_recon.wrappers.save_mni_fiducials osl_ephys.source_recon.wrappers.extract_polhemus_from_pos osl_ephys.source_recon.wrappers.extract_polhemus_from_elc osl_ephys.source_recon.wrappers.compute_surfaces osl_ephys.source_recon.wrappers.make_watershed_bem osl_ephys.source_recon.wrappers.coregister osl_ephys.source_recon.wrappers.forward_model osl_ephys.source_recon.wrappers.beamform osl_ephys.source_recon.wrappers.minimum_norm osl_ephys.source_recon.wrappers.parcellate osl_ephys.source_recon.wrappers.beamform_and_parcellate osl_ephys.source_recon.wrappers.minimum_norm_and_parcellate osl_ephys.source_recon.wrappers.find_template_subject osl_ephys.source_recon.wrappers.fix_sign_ambiguity osl_ephys.source_recon.wrappers.extract_rhino_files Module Contents --------------- .. py:function:: rescale_sensor_positions(outdir, subject, rescale) Wrapper to move sensor positions. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param rescale: List containing scaling factors for the x,y,z coordinates of the headshape points and fiducials: [xscale, yscale, zscale]. :type rescale: list, optional .. py:function:: extract_polhemus_from_info(outdir, subject, include_eeg_as_headshape=False, include_hpi_as_headshape=True, rescale=None, preproc_file=None, epoch_file=None) Wrapper function to extract fiducials/headshape points. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param include_eeg_as_headshape: Should we include EEG locations as headshape points? :type include_eeg_as_headshape: bool, optional :param include_hpi_as_headshape: Should we include HPI locations as headshape points? :type include_hpi_as_headshape: bool, optional :param rescale: List containing scaling factors for the x,y,z coordinates of the headshape points and fiducials: [xscale, yscale, zscale]. :type rescale: list, optional :param preproc_file: Path to the preprocessed fif file. :type preproc_file: str, optional :param epoch_file: Path to the preprocessed fif file. :type epoch_file: str, optional .. py:function:: extract_fiducials_from_fif(*args, **kwargs) Wrapper for extract_polhemus_from_info. .. py:function:: remove_stray_headshape_points(outdir, subject, nose=True) Remove stray headshape points. This function removes headshape points on the nose, neck and far from the head. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param noise: 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. :type noise: bool, optional .. py:function:: save_mni_fiducials(outdir, subject, filepath) Wrapper to save MNI fiducials. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param filepath: 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. :type filepath: str .. py:function:: extract_polhemus_from_pos(outdir, subject, filepath) Wrapper to save polhemus data from a .pos file. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param filepath: 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'. :type filepath: str .. py:function:: extract_polhemus_from_elc(outdir, subject, filepath, remove_headshape_near_nose=False) Wrapper to save polhemus data from an .elc file. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param filepath: 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'. :type filepath: str :param remove_headshape_near_nose: Should we remove any headshape points near the nose? :type remove_headshape_near_nose: bool, optional .. py:function:: compute_surfaces(outdir, subject, smri_file, include_nose=True, cleanup_files=True, recompute_surfaces=False, do_mri2mniaxes_xform=True, use_qform=False, reportdir=None) Wrapper for computing surfaces. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param smri_file: Path to the T1 weighted structural MRI file to use in source reconstruction. :type smri_file: str :param include_nose: Should we include the nose when we're extracting the surfaces? :type include_nose: bool, optional :param cleanup_files: Specifies whether to cleanup intermediate files in the surfaces directory. :type cleanup_files: bool, optional :param recompute_surfaces: Specifies whether or not to run compute_surfaces, if the passed in options have already been run. :type recompute_surfaces: bool, optional :param do_mri2mniaxes_xform: 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). :type do_mri2mniaxes_xform: bool, optional :param use_qform: Should we replace the sform with the qform? Useful if the sform code is incompatible with OSL, but the qform is compatible. :type use_qform: bool, optional :param reportdir: Path to report directory. :type reportdir: str, optional .. py:function:: make_watershed_bem(outdir, subject, overwrite=False, reportdir=None) Wrapper for making the watershed BEM. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param reportdir: Path to report directory. :type reportdir: str, optional .. py:function:: 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) Wrapper for coregistration. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param preproc_file: Path to the preprocessed fif file. :type preproc_file: str, optional :param epoch_file: Path to the preprocessed epochs fif file. :type epoch_file: str, optional :param surface_extraction_method: Method used to extract the surfaces. Can be 'fsl' or 'freesurfer'. :type surface_extraction_method: str, optional :param use_nose: Should we use the nose in the coregistration? :type use_nose: bool, optional :param use_headshape: Should we use the headshape points in the coregistration? :type use_headshape: bool, optional :param already_coregistered: Indicates that the data is already coregistered. :type already_coregistered: bool, optional :param allow_smri_scaling: 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'. :type allow_smri_scaling: bool, str, optional :param n_init: Number of initialisations for coregistration. Different defaults for surface_extraction_method='fsl' and surface_extraction_method='freesurfer' :type n_init: int, optional :param reportdir: Path to report directory. :type reportdir: str, optional .. py:function:: forward_model(outdir, subject, smri_file=None, surface_extraction_method='fsl', gridstep=8, model='Single Layer', source_space='volumetric', eeg=False, reportdir=None, **kwargs) Wrapper for computing the forward model. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param smri_file: Path to the T1 weighted structural MRI file to use in source reconstruction. Only required if using freesurfer and a volumentric source space. :type smri_file: str, optional :param surface_extraction_method: Method used to extract the surfaces. Can be 'fsl' or 'freesurfer'. :type surface_extraction_method: str, optional :param gridstep: A grid will be constructed with the spacing given by ``gridstep`` in mm, generating a volume source space. :type gridstep: int, optional :param model: 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) :type model: str, optional :param source_space: 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. :type source_space: str, optional :param eeg: Are we using EEG channels in the source reconstruction? :type eeg: bool, optional :param reportdir: Path to report directory. :type reportdir: str, optional .. py:function:: 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) Wrapper function for beamforming. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param preproc_file: Path to the preprocessed fif file. :type preproc_file: str :param epoch_file: Path to epoched preprocessed fif file. :type epoch_file: str :param chantypes: Channel types to use in beamforming. :type chantypes: str or list of str :param rank: Keys should be the channel types and the value should be the rank to use. :type rank: dict :param freq_range: Lower and upper band to bandpass filter before beamforming. If None, no filtering is done. :type freq_range: list, optional :param weight_norm: Beamformer weight normalisation. :type weight_norm: str, optional :param pick_ori: Orientation of the dipoles. :type pick_ori: str, optional :param reg: The regularization for the whitened data covariance. :type reg: float, optional :param reportdir: Path to report directory :type reportdir: str, optional .. py:function:: 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) Wrapper function for MNE source localization. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param preproc_file: Path to the preprocessed fif file. :type preproc_file: str :param epoch_file: Path to epoched preprocessed fif file. :type epoch_file: str :param chantypes: List of channel types to include. :type chantypes: list :param rank: Rank of the noise covariance matrix. :type rank: int :param surface_extraction_method: Method used to extract the surfaces. Can be 'fsl' or 'freesurfer'. :type surface_extraction_method: str :param depth: Depth weighting. :type depth: float, optional :param loose: Loose orientation constraint. :type loose: float, optional :param lambda2: Regularization parameter for the minimum norm estimate. Use 1/9 for MEG, 1 for EEG. :type lambda2: float :param pick_ori: Orientation of the dipoles. :type pick_ori: str :param freq_range: Lower and upper band to bandpass filter before source estimation. If None, no filtering is done. :type freq_range: list, optional :param reportdir: Path to report directory. :type reportdir: str, optional .. py:function:: 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) Wrapper function for parcellation. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param preproc_file: Path to the preprocessed fif file. :type preproc_file: str :param epoch_file: Path to epoched preprocessed fif file. :type epoch_file: str :param parcellation_file: Path to the parcellation file to use. :type parcellation_file: str :param method: Method to use in the parcellation. :type method: str :param orthogonalisation: Options are 'symmetric', 'local', None. If 'local', neighbour_distance must be specified. :type orthogonalisation: str, None :param source_space: Source model to use. Can be 'volumetric' (/'vol') or 'surface' (/'surf'). :type source_space: str :param surface_extraction_method: Method used to extract the surfaces. Can be 'fsl' or 'freesurfer'. :type surface_extraction_method: str :param source_method: Method used for source reconstruction. Can be 'lcmv' or one of the MNE methods ('mne', 'dspm', 'sloreta', 'eloreta'). :type source_method: str, optional :param spatial_resolution: 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. :type spatial_resolution: int, optional :param reference_brain: 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'. :type reference_brain: str, optional :param voxel_trans: Should we standardise ('ztrans') or de-mean ('demean') the voxel time courses? If None, no normalisation is applied. :type voxel_trans: str, optional :param extra_chans: 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. :type extra_chans: str or list of str, optional :param neighbour_distance: Distance in mm between parcel centers to consider neighbours for orthogonalisation='local'. :type neighbour_distance: float, optional :param reportdir: Path to report directory. :type reportdir: str, optional .. py:function:: 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) Wrapper function for beamforming and parcellation. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param preproc_file: Path to the preprocessed fif file. :type preproc_file: str :param epoch_file: Path to epoched preprocessed fif file. :type epoch_file: str :param chantypes: Channel types to use in beamforming. :type chantypes: str or list of str :param rank: Keys should be the channel types and the value should be the rank to use. :type rank: dict :param parcellation_file: Path to the parcellation file to use. :type parcellation_file: str :param method: Method to use in the parcellation. :type method: str :param orthogonalisation: Options are 'symmetric', 'local', None. If 'local', neighbour_distance must be specified. :type orthogonalisation: str, None :param freq_range: Lower and upper band to bandpass filter before beamforming. If None, no filtering is done. :type freq_range: list, optional :param weight_norm: Beamformer weight normalisation. :type weight_norm: str, optional :param pick_ori: Orientation of the dipoles. :type pick_ori: str, optional :param reg: The regularization for the whitened data covariance. :type reg: float, optional :param spatial_resolution: 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. :type spatial_resolution: int, optional :param reference_brain: '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. :type reference_brain: str, optional :param extra_chans: 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. :type extra_chans: str or list of str, optional :param neighbour_distance: Distance in mm between parcel centers to consider neighbours for orthogonalisation='local'. :type neighbour_distance: float, optional :param reportdir: Path to report directory. :type reportdir: str, optional .. py:function:: 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) Wrapper function for minimum_norm and parcellation. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param preproc_file: Path to the preprocessed fif file. :type preproc_file: str :param epoch_file: Path to epoched preprocessed fif file. :type epoch_file: str :param source_method: Method to use for inverse modelling (e.g., MNE, eLORETA). :type source_method: str :param source_space: Source model to use (e.g., volumetric, surface). :type source_space: str :param chantypes: List of channel types to include. :type chantypes: list :param rank: Rank of the noise covariance matrix. :type rank: int :param method: Method to use in the parcellation. :type method: str :param parcellation_file: Path to the parcellation file to use. :type parcellation_file: str :param orthogonalisation: Options are 'symmetric', 'local', None. If 'local', neighbour_distance must be specified. :type orthogonalisation: str, None :param surface_extraction_method: Method used for surface extraction. Can be 'freesurfer' or 'fsl'. :type surface_extraction_method: str, optional :param depth: Depth weighting. :type depth: float, optional :param loose: Loose orientation constraint. :type loose: float, optional :param lambda2: Regularization parameter for the minimum norm estimate. Use 1/9 for MEG, 1 for EEG. :type lambda2: float :param pick_ori: Orientation of the dipoles. :type pick_ori: str :param freq_range: Lower and upper band to bandpass filter before beamforming. If None, no filtering is done. :type freq_range: list, optional :param spatial_resolution: 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. :type spatial_resolution: int, optional :param reference_brain: 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'. :type reference_brain: str, optional :param voxel_trans: Should we standardise ('ztrans') or de-mean ('demean') the voxel time courses? If None, no normalisation is applied. :type voxel_trans: str, optional :param extra_chans: 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. :type extra_chans: str or list of str, optional :param neighbour_distance: Distance in mm between parcel centers to consider neighbours for orthogonalisation='local'. :type neighbour_distance: float, optional :param reportdir: Path to report directory. :type reportdir: str, optional .. py:function:: find_template_subject(outdir, subjects, n_embeddings=1, standardize=True, epoched=False, source_method='lcmv') 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'. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subjects: Subjects to include. :type subjects: str :param n_embeddings: Number of time-delay embeddings that we will use (if we are doing any). :type n_embeddings: int, optional :param standardize: Should we standardize (z-transform) the data before sign flipping? :type standardize: bool, optional :param epoched: Are we performing sign flipping on parc-raw.fif (epoched=False) or parc-epo.fif files (epoched=True)? :type epoched: bool, optional :param source_method: Method to used for inverse modelling (e.g., LCMV, MNE, eLORETA). :type source_method: str, optional :returns: **template** -- Template subject. :rtype: str .. py:function:: fix_sign_ambiguity(outdir, subject, preproc_file, template, n_embeddings, standardize, n_init, n_iter, max_flips, epoched=False, source_method='lcmv', reportdir=None) Wrapper function for fixing the dipole sign ambiguity. :param outdir: Path to where to output the source reconstruction files. :type outdir: str :param subject: Subject name/id. :type subject: str :param preproc_file: Path to the preprocessed fif file. :type preproc_file: str :param template: Template subject. :type template: str :param n_embeddings: Number of time-delay embeddings that we will use (if we are doing any). :type n_embeddings: int :param standardize: Should we standardize (z-transform) the data before sign flipping? :type standardize: bool :param n_init: Number of initializations. :type n_init: int :param n_iter: Number of sign flipping iterations per subject to perform. :type n_iter: int :param max_flips: Maximum number of channels to flip in an iteration. :type max_flips: int :param epoched: Are we performing sign flipping on parc-raw.fif (epoched=False) or parc-epo.fif files (epoched=True)? :type epoched: bool, optional :param source_method: Method to used for inverse modelling (e.g., LCMV, MNE, eLORETA). :type source_method: str, optional :param reportdir: Path to report directory. :type reportdir: str, optional .. py:function:: extract_rhino_files(outdir, subject, old_outdir) Wrapper function for extracting RHINO files from a previous run. :param outdir: Path to the NEW source reconstruction directory. :type outdir: str :param subject: Subject name/id. :type subject: str :param old_outdir: OLD source reconstruction directory to copy RHINO files to. :type old_outdir: str