osl_ephys.source_recon.parcellation =================================== .. py:module:: osl_ephys.source_recon.parcellation .. autoapi-nested-parse:: Functions to handle parcellation. Functions --------- .. autoapisummary:: osl_ephys.source_recon.parcellation.load_parcellation_description osl_ephys.source_recon.parcellation.load_parcellation osl_ephys.source_recon.parcellation._find_package_file osl_ephys.source_recon.parcellation._find_freesurfer_file osl_ephys.source_recon.parcellation.find_file osl_ephys.source_recon.parcellation.guess_parcellation osl_ephys.source_recon.parcellation.vol_parcellate_timeseries osl_ephys.source_recon.parcellation._get_parcel_timeseries osl_ephys.source_recon.parcellation.surf_parcellate_timeseries osl_ephys.source_recon.parcellation.resample_parcellation osl_ephys.source_recon.parcellation.local_orthogonalise osl_ephys.source_recon.parcellation.symmetric_orthogonalise osl_ephys.source_recon.parcellation.parcel_centers osl_ephys.source_recon.parcellation.plot_parcellation osl_ephys.source_recon.parcellation.plot_psd osl_ephys.source_recon.parcellation.plot_correlation osl_ephys.source_recon.parcellation._parcel_timeseries2nii osl_ephys.source_recon.parcellation.convert2niftii osl_ephys.source_recon.parcellation.convert2mne_raw osl_ephys.source_recon.parcellation.convert2mne_epochs osl_ephys.source_recon.parcellation.spatial_dist_adjacency osl_ephys.source_recon.parcellation.parcel_vector_to_voxel_grid osl_ephys.source_recon.parcellation.convert2source_estimate osl_ephys.source_recon.parcellation.plot_source_topo Module Contents --------------- .. py:function:: load_parcellation_description(parcellation_file, freesurfer=False, subject=None) Load a parcellation description file. :param parcellation_file: Path to parcellation file. Function will look for a xml file with same name but .xml extension. :type parcellation_file: str :param freesurfer: Is this a FreeSurfer parcellation? :type freesurfer: bool, optional :param subject: Subject ID. Only needed for FreeSurfer parcellations. :type subject: str :returns: **df** -- Dictionary with keys 'index', 'label', 'x', 'y', 'z' for each parcel. :rtype: dict .. py:function:: load_parcellation(parcellation_file, freesurfer=False, subject=None) Load a parcellation file. :param parcellation_file: Path to parcellation file. :type parcellation_file: str :param freesurfer: Are we loading a FreeSurfer parcellation? :type freesurfer: bool, optional :param subject: Subject ID. Only needed for FreeSurfer parcellations. :type subject: str :returns: **parcellation** -- Parcellation. :rtype: nibabel image or mne.Label .. py:function:: _find_package_file(filename) .. py:function:: _find_freesurfer_file(filename) .. py:function:: find_file(filename, freesurfer=False) Look for a parcellation file within the package. :param filename: Path to parcellation file to look for. :type filename: str :param freesurfer: Should we look in the freesurfer directory? :type freesurfer: bool, optional :returns: **filename** -- Path to parcellation file found. :rtype: str .. py:function:: guess_parcellation(data, return_path=False) Guess parcellation file from data. :param data: Data to guess parcellation from. first dimension is assumed to be parcels. :type data: vector or matrix :param return_path: If True, return path to parcellation file, otherwise return filename. :type return_path: bool :returns: **filename** -- Path to parcellation file. :rtype: str .. py:function:: vol_parcellate_timeseries(parcellation_file, voxel_timeseries, voxel_coords, method, working_dir) Parcellate a voxel time series. :param parcellation_file: Parcellation file (or path to parcellation file). :type parcellation_file: str :param voxel_timeseries: (nvoxels x ntpts) or (nvoxels x ntpts x ntrials) data to be parcellated. Data is assumed to be in same space as the parcellation (e.g. typically corresponds to the output from beamforming.transform_recon_timeseries). :type voxel_timeseries: numpy.ndarray :param voxel_coords: (nvoxels x 3) coordinates of voxel_timeseries in mm in same space as parcellation (e.g. typically corresponds to the output from beamforming.transform_recon_timeseries). :type voxel_coords: numpy.ndarray :param method: ``'pca'`` - take 1st PC in each parcel ``'spatial_basis'`` - The parcel time-course for each spatial map is the 1st PC from all voxels, weighted by the spatial map. If the parcellation is unweighted and non-overlapping, 'spatialBasis' will give the same result as 'PCA' except with a different normalization. :type method: str :param working_dir: Directory to put temporary file in. If None, attempt to use same directory as passed in parcellation. :type working_dir: str :returns: * **parcel_timeseries** (*numpy.ndarray*) -- nparcels x ntpts, or nparcels x ntpts x ntrials, parcellated data. * **voxel_weightings** (*numpy.ndarray*) -- nvoxels x nparcels, Voxel weightings for each parcel, corresponds to parcel_data = voxel_weightings.T * voxel_data * **voxel_assignments** (*bool numpy.ndarray*) -- nvoxels x nparcels, Boolean assignments indicating for each voxel the winner takes all parcel it belongs to. .. py:function:: _get_parcel_timeseries(voxel_timeseries, parcellation_asmatrix, method='spatial_basis') Calculate parcel timeseries. :param voxel_timeseries: (nvoxels x ntpts) or (nvoxels x ntpts x ntrials) and is assumed to be on the same grid as parcellation (typically output by beamforming.transform_recon_timeseries). :type voxel_timeseries: numpy.ndarray :param parcellation_asmatrix: (nvoxels x nparcels) and is assumed to be on the same grid as voxel_timeseries. :type parcellation_asmatrix: numpy.ndarray :param method: ``'pca'`` - take 1st PC of voxels ``'spatial_basis'`` - The parcel time-course for each spatial map is the 1st PC from all voxels, weighted by the spatial map. If the parcellation is unweighted and non-overlapping, 'spatialBasis' will give the same result as 'PCA' except with a different normalization. :type method: str :returns: * **parcel_timeseries** (*numpy.ndarray*) -- nparcels x ntpts, or nparcels x ntpts x ntrials * **voxel_weightings** (*numpy.ndarray*) -- nvoxels x nparcels Voxel weightings for each parcel to compute parcel_timeseries from voxel_timeseries * **voxel_assignments** (*bool numpy.ndarray*) -- nvoxels x nparcels Boolean assignments indicating for each voxel the winner takes all parcel it belongs to .. py:function:: surf_parcellate_timeseries(subject_dir, subject, stc, method, parcellation_file) Save parcellated data as a fif file. :param subject_dir: Path to subject directory. :type subject_dir: str :param subject: Subject ID. :type subject: str :param stc: Source estimate. :type stc: mne.SourceEstimate :param method: Parcellation method. Can be 'pca_flip', 'max', 'mean', 'mean_flip', 'auto' :type method: str :param parcellation_file: Parcellation name. :type parcellation_file: str .. py:function:: resample_parcellation(parcellation_file, voxel_coords, working_dir=None, freesurfer=False) Resample parcellation so that its voxel coords correspond (using nearest neighbour) to passed in voxel_coords. Passed in voxel_coords and parcellation must be in the same space, e.g. MNI. Used to make sure that the parcellation's voxel coords are the same as the voxel coords for some timeseries data, before calling _get_parcel_timeseries. :param parcellation_file: Path to parcellation file. In same space as voxel_coords. :type parcellation_file: str :param voxel_coords: (nvoxels x 3) coordinates in mm in same space as parcellation. :param working_dir: Dir to put temp file in. If None, attempt to use same dir as passed in parcellation. :type working_dir: str :param freesurfer: If True, parcellation_file is a freesurfer parcellation. Otherwise, it is a nifti file. :type freesurfer: bool :returns: **parcellation_asmatrix** -- (nvoxels x nparcels) resampled parcellation :rtype: numpy.ndarray .. py:function:: local_orthogonalise(timeseries, parcellation_file=None, dist=None, adjacency=None) Returns a local orthogonalisation of the timeseries, where the time series of local neighbours are regressed out with multiple linear regression. :param timeseries: (nparcels x ntpts) or (nparcels x ntpts x ntrials) data to orthoganlise. In the latter case, the ntpts and ntrials dimensions are concatenated. :type timeseries: numpy.ndarray :param parcellation_file: If None, adjacency must be provided. :type parcellation_file: nifti parcellation file :param dist: Distance in mm to consider as neighbours. Must be provided together with parcellation file. If None, adjacency must be provided. :type dist: float :param adjacency: nparcels x nparcels binary adjacency matrix. :type adjacency: numpy.ndarray :returns: **ortho_timeseries** -- (nparcels x ntpts) or (nparcels x ntpts x ntrials) orthoganalised data :rtype: numpy.ndarray .. py:function:: symmetric_orthogonalise(timeseries, maintain_magnitudes=False, compute_weights=False) Returns orthonormal matrix L which is closest to A, as measured by the Frobenius norm of (L-A). The orthogonal matrix is constructed from a singular value decomposition of A. If maintain_magnitudes is True, returns the orthogonal matrix L, whose columns have the same magnitude as the respective columns of A, and which is closest to A, as measured by the Frobenius norm of (L-A). :param timeseries: (nparcels x ntpts) or (nparcels x ntpts x ntrials) data to orthoganlise. In the latter case, the ntpts and ntrials dimensions are concatenated. :type timeseries: numpy.ndarray :param maintain_magnitudes: :type maintain_magnitudes: bool :param compute_weights: :type compute_weights: bool :returns: * **ortho_timeseries** (*numpy.ndarray*) -- (nparcels x ntpts) or (nparcels x ntpts x ntrials) orthoganalised data * **weights** (*numpy.ndarray*) -- (optional output depending on compute_weights flag) weighting matrix such that, ortho_timeseries = timeseries * weights .. rubric:: References Colclough, G. L., Brookes, M., Smith, S. M. and Woolrich, M. W., "A symmetric multivariate leakage correction for MEG connectomes," NeuroImage 117, pp. 439-448 (2015) .. py:function:: parcel_centers(parcellation_file, freesurfer=False) Get coordinates of parcel centers. :param parcellation_file: Path to parcellation file. :type parcellation_file: str :param freesurfer: Is the parcellation a FreeSurfer parcellation? :type freesurfer: bool :returns: **coords** -- Coordinates of each parcel. Shape is (n_parcels, 3). :rtype: np.ndarray .. py:function:: plot_parcellation(parcellation_file, **kwargs) Plots a parcellation. :param parcellation_file: Path to parcellation file. :type parcellation_file: str :param kwargs: Keyword arguments to pass to nilearn.plotting.plot_markers. :type kwargs: keyword arguments .. py:function:: plot_psd(parc_ts, fs, parcellation_file, filename, freq_range=None, freesurfer=False) Plot PSD of each parcel time course. :param parc_ts: (parcels, time) or (parcels, time, epochs) time series. :type parc_ts: np.ndarray :param fs: Sampling frequency in Hz. :type fs: float :param parcellation_file: Path to parcellation file. :type parcellation_file: str :param filename: Output filename. :type filename: str :param freq_range: Low and high frequency in Hz. :type freq_range: list of len 2 :param freesurfer: Is the parcellation a FreeSurfer parcellation? :type freesurfer: bool .. py:function:: plot_correlation(parc_ts, filename) Plot correlation between parcel time courses. :param parc_ts: (parcels, time) or (parcels, time, epochs) time series. :type parc_ts: np.ndarray :param filename: Output filename. :type filename: str .. py:function:: _parcel_timeseries2nii(parcellation_file, parcel_timeseries_data, voxel_weightings, voxel_assignments, voxel_coords, out_nii_fname=None, working_dir=None, times=None, method='assignments', freesurfer=False) Outputs parcel_timeseries_data as a niftii file using passed in parcellation. The parcellation and parcel_timeseries_data need to have the same number of parcels. :param parcellation_file: Path to parcellation file. :type parcellation_file: str :param parcel_timeseries_data: Needs to be nparcels x ntpts :type parcel_timeseries_data: numpy.ndarray :param voxel_weightings: (nvoxels x nparcels) voxel weightings for each parcel to compute parcel_timeseries from voxel_timeseries. :type voxel_weightings: numpy.ndarray :param voxel_assignments: (nvoxels x nparcels) boolean assignments indicating for each voxel the winner takes all parcel it belongs to. :type voxel_assignments: bool numpy.ndarray :param voxel_coords: (nvoxels x 3) coordinates of voxel_timeseries in mm in same space as parcellation (e.g. typically corresponds to the output from beamforming.transform_recon_timeseries). :type voxel_coords: numpy.ndarray :param working_dir: Directory name to put files in. :type working_dir: str :param out_nii_fname: Output name to put files in. :type out_nii_fname: str :param times: (ntpts,) times points in seconds. Will assume that time points are regularly spaced. Used to set nii file up correctly. :type times: array :param method: "weights" or "assignments" :type method: str :param freesurfer: If True, parcellation_file is a freesurfer parcellation. Otherwise, it is a nifti file. :type freesurfer: bool :returns: **out_nii_fname** -- Output nii filename, will be output at spatial resolution of parcel_timeseries['voxel_coords']. :rtype: str .. py:function:: convert2niftii(parc_data, parcellation_file, mask_file, tres=1, tmin=0, freesurfer=False) Convert parcellation to NIfTI. Takes (nparcels) or (nvolumes x nparcels) parc_data and returns (xvoxels x yvoxels x zvoxels x nvolumes) niftii file containing parc_data on a volumetric grid. :param parc_data: (nparcels) or (nvolumes x nparcels) parcel data. :type parc_data: np.ndarray :param parcellation_file: Path to niftii parcellation file. :type parcellation_file: str :param mask_file: Path to niftii parcellation mask file. :type mask_file: str :param tres: Resolution of 4th dimension in secs :type tres: float :param tmin: Value of first time point in secs :type tmin: float :param freesurfer: If True, parcellation_file is a freesurfer parcellation. Otherwise, it is a nifti file. :type freesurfer: bool :returns: **nii** -- (xvoxels x yvoxels x zvoxels x nvolumes) nib.Nifti1Image containing parc_data on a volumetric grid. :rtype: nib.Nifti1Image .. py:function:: convert2mne_raw(parc_data, raw, parcel_names=None, extra_chans='stim') Create and returns an MNE raw object that contains parcellated data. :param parc_data: (nparcels x ntpts) parcel data. :type parc_data: np.ndarray :param raw: mne.io.raw object that produced parc_data via source recon and parcellation. Info such as timings and bad segments will be copied from this to parc_raw. :type raw: mne.Raw :param parcel_names: List of strings indicating names of parcels. If None then names are set to be parcel_0,...,parcel_{n_parcels-1}. :type parcel_names: list of str :param extra_chans: Extra channels, e.g. 'stim' or 'emg', to include in the parc_raw object. Defaults to 'stim'. stim channels are always added to parc_raw if they are present in raw. :type extra_chans: str or list of str :returns: **parc_raw** -- Generated parcellation in mne.Raw format. :rtype: mne.Raw .. py:function:: convert2mne_epochs(parc_data, epochs, parcel_names=None) Create and returns an MNE Epochs object that contains parcellated data. :param parc_data: (nparcels x ntpts x epochs) parcel data. :type parc_data: np.ndarray :param epochs: mne.io.raw object that produced parc_data via source recon and parcellation. Info such as timings and bad segments will be copied from this to parc_raw. :type epochs: mne.Epochs :param parcel_names: List of strings indicating names of parcels. If None then names are set to be parcel_0,...,parcel_{n_parcels-1}. :type parcel_names: list of str :returns: **parc_epo** -- Generated parcellation in :py:class: mne.Epochs` format. :rtype: mne.Epochs .. py:function:: spatial_dist_adjacency(parcellation_file, dist, verbose=False) Compute adjacency from distances between parcels. :param parcellation_file: Path to parcellation file. :type parcellation_file: str :param dist: Maximum (geodesic) distance in mm for two parcels to within to be considered as neighbours. :type dist: float :param verbose: Should we print the distance between parcels that are considered neighbours? :type verbose: bool :returns: **adj_mat** -- (n_parcels, n_parcels) matrix of zeros (indicating not neighbours) and ones (indicating parcels are neighbours). :rtype: np.ndarray .. py:function:: parcel_vector_to_voxel_grid(mask_file, parcellation_file, vector, freesurfer=False) Takes a vector of parcel values and return a 3D voxel grid. :param mask_file: Mask file for the voxel grid. Must be a NIFTI file. :type mask_file: str :param parcellation_file: Parcellation file. Must be a NIFTI file. :type parcellation_file: str :param vector: Value at each parcel. Shape must be (n_parcels,). :type vector: np.ndarray :param freesurfer: If True, parcellation_file is a freesurfer parcellation. Otherwise, it is a nifti file. :type freesurfer: bool :returns: **voxel_grid** -- Value at each voxel. Shape is (x, y, z), where :code:`x`, :code:`y` and :code:`z` correspond to 3D voxel locations. :rtype: np.ndarray .. py:function:: convert2source_estimate(subjects_dir, data, parc=None, reference_brain='fsaverage') Convert parcellated data to a source estimate. :param subjects_dir: Path to subjects directory. :type subjects_dir: str :param data: Data to convert. :type data: mne.Evoked or mne.Epochs :param parc: Parcellation name. :type parc: str :param reference_brain: Reference brain. Default is 'fsaverage'. :type reference_brain: str :returns: **stc** -- Source estimate. :rtype: mne.SourceEstimate .. py:function:: plot_source_topo(data_map, parcellation_file=None, mask_file='MNI152_T1_8mm_brain.nii.gz', axis=None, cmap=None, vmin=None, vmax=None, alpha=0.7, freesurfer=False) Plot a data map on a cortical surface. Wrapper for nilearn.plotting.plot_glass_brain. :param data_map: Vector of data values to plot (nparc,) :type data_map: array_like :param parcellation_file: Filepath of parcellation file to plot data on :type parcellation_file: str :param mask_file: Filepath of mask file to plot data on (Default value = 'MNI152_T1_8mm_brain.nii.gz') :type mask_file: str :param axis: Axis to plot into (Default value = None) :type axis: {None or axis handle} :param cmap: Colormap to use for plotting (Default value = None) :type cmap: {None or matplotlib colormap} :param vmin: Minimum value for colormap (Default value = None) :type vmin: {None or float} :param vmax: Maximum value for colormap (Default value = None) :type vmax: {None or float} :param alpha: Alpha value for colormap (Default value = None) :type alpha: {None or float} :param freesurfer: If True, parcellation_file is a freesurfer parcellation. Otherwise, it is a nifti file. :type freesurfer: bool :returns: **image** -- AxesImage object :rtype: :py:class:`matplotlib.image.AxesImage `