osl_dynamics.meeg.parcellation#

Parcellation.

Classes#

Parcellation

Class for reading parcellation files.

Functions#

plot_parcellation(parcellation, **kwargs)

Plot a parcellation.

parcel_vector_to_voxel_grid(mask_file, ...[, ...])

Takes a vector of parcel values and return a 3D voxel grid.

parcellate(fns, voxel_data, voxel_coords, method, ...)

Parcellate data.

save_as_fif(parcel_data, raw, filename[, extra_chans])

Save parcellated data as a fif file.

plot_psds(parc_fif, parcellation_file[, fmin, fmax, ...])

Plot PSD of each parcel time course.

save_qc_plots(parc_fif, parcellation_file[, ...])

Save parcellation QC plots.

convert_to_mne_raw(data, raw[, ch_names, extra_chans])

Convert an array to an MNE Raw object, copying metadata from a reference.

Module Contents#

class osl_dynamics.meeg.parcellation.Parcellation(file)[source]#

Class for reading parcellation files.

Parameters:

file (str) – Path to parcellation file.

file[source]#
parcellation[source]#
dims[source]#
n_parcels[source]#
data()[source]#
Return type:

numpy.ndarray

nonzero()[source]#
Return type:

list

nonzero_coords()[source]#
Return type:

list

weights()[source]#
Return type:

list

roi_centers()[source]#

Centroid of each parcel.

Return type:

numpy.ndarray

plot(**kwargs)[source]#
Return type:

object

static find_files()[source]#
Return type:

list[str]

osl_dynamics.meeg.parcellation.plot_parcellation(parcellation, **kwargs)[source]#

Plot a parcellation.

Parameters:
Return type:

object

osl_dynamics.meeg.parcellation.parcel_vector_to_voxel_grid(mask_file, parcellation_file, vector, remove_subcortical_voxels=False)[source]#

Takes a vector of parcel values and return a 3D voxel grid.

Parameters:

  • mask_file (str) – Mask file for the voxel grid. Must be a NIFTI file.

  • parcellation_file (str) – Parcellation file. Must be a NIFTI file.

  • vector (np.ndarray) – Value at each parcel. Shape must be (n_parcels,).

  • remove_subcortical_voxels (bool, optional) – Should we set the subcortical voxels to np.nan?

Returns:

voxel_grid – Value at each voxel. Shape is (x, y, z), where x, y and z correspond to 3D voxel locations.

Return type:

np.ndarray

osl_dynamics.meeg.parcellation.parcellate(fns, voxel_data, voxel_coords, method, parcellation_file, orthogonalisation=None)[source]#

Parcellate data.

Parameters:

  • fns (OSLFilenames) – Container for OSL filenames.

  • voxel_data (np.ndarray) – (nvoxels x n_time) or (nvoxels x n_time x n_trials) and is assumed to be on the same grid as parcellation.

  • voxel_coords (numpy.ndarray) – (nvoxels x 3) coordinates in mm in same space as parcellation.

  • method (str, optional) –

    ‘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, ‘spatial_basis’ will give the same result as ‘pca’ except with a different normalisation.

    ’centroid’ - Use the time course of the voxel nearest to each

    parcel centroid.

  • parcellation_file (str) – Path to parcellation file. In same space as voxel_coords.

  • orthogonalisation (str, optional) – Method for orthogonalising the data. Can be None or ‘symmetric’.

Returns:

parcel_data – Parcellated data. Shape is (parcels, time) or (parcels, time, epochs).

Return type:

np.ndarray

osl_dynamics.meeg.parcellation.save_as_fif(parcel_data, raw, filename, extra_chans=None)[source]#

Save parcellated data as a fif file.

Parameters:

  • parcel_data (np.ndarray) – (parcels, time) or (parcels, time, epochs) data.

  • raw (mne.Raw or mne.Epochs) – MNE Raw or Epochs objects to get info from.

  • filename (str) – Output file path.

  • extra_chans (str or list of str) – 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.

Return type:

None

osl_dynamics.meeg.parcellation.plot_psds(parc_fif, parcellation_file, fmin=0.5, fmax=45, filename=None)[source]#

Plot PSD of each parcel time course.

Parameters:

  • parc_fif (mne.Raw or mne.Epochs) – MNE Raw or Epochs object containing the parcel data.

  • parcellation_file (str) – Path to parcellation file.

  • fmin (float, optional) – Minimum frequency.

  • fmax (float, optional) – Maximum frequency.

  • filename (str, optional) – Output filename.

Return type:

None

osl_dynamics.meeg.parcellation.save_qc_plots(parc_fif, parcellation_file, output_dir=None, power_maps=False, show=False, cmap='hot')[source]#

Save parcellation QC plots.

Saves the following files to output_dir: - psd_topo.png: PSD topography plot - power_maps.png: composite band power maps (only if power_maps=True)

Parameters:

  • parc_fif (str) – Path to parcellated fif file.

  • parcellation_file (str) – Parcellation file name.

  • output_dir (str or Path, optional) – Directory to save plots to. Defaults to the directory containing parc_fif.

  • power_maps (bool, optional) – Whether to create band power map plots. Default is False.

  • show (bool, optional) – Whether to display the plots interactively. Default is False.

  • cmap (str, optional) – Colormap for power maps.

Return type:

None

osl_dynamics.meeg.parcellation.convert_to_mne_raw(data, raw, ch_names=None, extra_chans=None)[source]#

Convert an array to an MNE Raw object, copying metadata from a reference.

If data has fewer time points than raw, bad segments are re-inserted as zeros so that the output has the same length as raw.

Parameters:

  • data (np.ndarray) – (n_channels, n_samples) data array.

  • raw (mne.io.Raw) – Reference Raw object. Timing, annotations, filter settings, description and extra channels are copied from this object.

  • ch_names (list of str, optional) – Channel names. Defaults to channel_0, ..., channel_{n-1}.

  • extra_chans (str or list of str, optional) – Extra channel types (e.g. "stim", "emg") to copy from raw. Defaults to None (no extra channels).

Returns:

new_raw – New Raw object containing data with metadata from raw.

Return type:

mne.io.Raw