osl_dynamics.analysis.power#

Functions to calculate and save network power maps.

Note

This module is used in the following tutorials:

Module Contents#

Functions#

sliding_window_power(data, window_length[, step_size, ...])

Calculate sliding window power.

variance_from_spectra(frequencies, power_spectra[, ...])

Calculates variance from power spectra.

parcel_vector_to_voxel_grid(mask_file, ...)

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

save(power_map, mask_file, parcellation_file[, ...])

Saves power maps.

multi_save(group_power_map, session_power_map, ...[, ...])

Saves group level and array level power maps.

independent_components_to_volumetric_maps(...[, ...])

Independent components to volumetric spatial map.

independent_components_to_surface_maps(...[, output_file])

Independent components to surface spatial map.

Attributes#

_logger

osl_dynamics.analysis.power._logger[source]#
osl_dynamics.analysis.power.sliding_window_power(data, window_length, step_size=None, power_type='mean', concatenate=False)[source]#

Calculate sliding window power.

Parameters:

  • data (list or np.ndarray) – Time series data. Shape must be (n_sessions, n_samples, n_channels) or (n_samples, n_channels).

  • window_length (int) – Window length in samples.

  • step_size (int, optional) – Number of samples to slide the window along the time series. If None is passed, then a 50% overlap is used.

  • power_type (str, optional) – Type of power to calculate. Can be "mean" or "var".

  • concatenate (bool, optional) – Should we concatenate the sliding window power from each array into one big time series?

Returns:

sliding_window_power – Time series of power vectors. Shape is (n_sessions, n_windows, n_channels) or (n_windows, n_channels).

Return type:

list or np.ndarray

osl_dynamics.analysis.power.variance_from_spectra(frequencies, power_spectra, components=None, frequency_range=None, method='mean')[source]#

Calculates variance from power spectra.

Parameters:

  • frequencies (np.ndarray) – Frequency axis of the PSDs. Only used if frequency_range is given. Shape must be (n_freq,).

  • power_spectra (np.ndarray) – Power/cross spectra for each channel. Shape must be (n_channels, n_channels) or (n_channels,).

  • components (np.ndarray, optional) – Spectral components. Shape must be (n_components, n_freq).

  • frequency_range (list, optional) – Frequency range in Hz to integrate the PSD over. Default is full range.

  • method (str) – Should take the sum of the PSD over the frequency range (method="sum"), the integral of the PSD ("integral"), or take the average value of the PSD (method="mean").

Returns:

var – Variance over a frequency band for each component of each mode. Shape is (n_components, n_modes, n_channels) or (n_modes, n_channels) or (n_channels,).

Return type:

np.ndarray

osl_dynamics.analysis.power.parcel_vector_to_voxel_grid(mask_file, parcellation_file, vector)[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,).

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.analysis.power.save(power_map, mask_file, parcellation_file, filename=None, component=0, subtract_mean=False, mean_weights=None, plot_kwargs=None, show_plots=True, combined=False, titles=None)[source]#

Saves power maps.

This function is a wrapper for nilearn.plotting.plot_img_on_surf.

Parameters:

  • power_map (np.ndarray) – Power map to save. Can be of shape: (n_components, n_modes, n_channels), (n_modes, n_channels) or (n_channels,). A (…, n_channels, n_channels) array can also be passed. Warning: this function cannot be used if n_modes=n_channels.

  • mask_file (str) – Mask file used to preprocess the training data.

  • parcellation_file (str) – Parcellation file used to parcellate the training data.

  • filename (str, optional) – Output filename. If extension is .nii.gz the power map is saved as a NIFTI file. Or if the extension is png/svg/pdf, it is saved as images. If None is passed then the image is shown on screen and the Matplotlib objects are returned.

  • component (int, optional) – Spectral component to save.

  • subtract_mean (bool, optional) – Should we subtract the mean power across modes?

  • mean_weights (np.ndarray, optional) – Numpy array with weightings for each mode to use to calculate the mean. Default is equal weighting.

  • plot_kwargs (dict, optional) –

    Keyword arguments to pass to nilearn.plotting.plot_img_on_surf.

  • show_plots (bool, optional) – Should the individual plots be shown on screen (for Juptyer notebooks)?

  • combined (bool, optional) – Should the individual plots be combined into a single image? The combined image is always shown on screen (for Juptyer notebooks). Note if True is passed, the individual images will be deleted.

  • titles (list, optional) – List of titles for each power plot. Only used if combined=True.

Returns:

  • figures (list of plt.figure) – List of Matplotlib figure object. Only returned if filename=None.

  • axes (list of plt.axis) – List of Matplotlib axis object(s). Only returned if filename=None.

Examples

Plot power maps with customise display:

power.save(
    ...,
    plot_kwargs={
        "cmap": "RdBu_r",
        "bg_on_data": 1,
        "darkness": 0.4,
        "alpha": 1,
    },
)
osl_dynamics.analysis.power.multi_save(group_power_map, session_power_map, mask_file, parcellation_file, filename=None, sessions=None, subtract_mean=False, mean_weights=None, plot_kwargs=None)[source]#

Saves group level and array level power maps.

When training session-specific models we want to plot the group-level map and session-specific deviations. This function is a wrapper for power.save, which helps us plot power maps for session-specific models.

Parameters:

  • group_power_map (np.ndarray) – Group level power map to save. Can be of shape: (n_modes, n_channels) or (n_channels,). A (…, n_channels, n_channels) can also be passed. Warning: this function cannot be used if n_modes is equal to n_channels.

  • session_power_map (np.ndarray) – Session-level power maps to save. Can be of shape: (n_sessions, n_modes, n_channels), (n_modes, n_channels) or (n_channels,). A (…, n_channels, n_channels) array can also be passed. Warning: this function cannot be used if n_modes=n_channels.

  • mask_file (str) – Mask file used to preprocess the training data.

  • parcellation_file (str) – Parcellation file used to parcellate the training data.

  • filename (str, optional) – Output filename. If extension is .nii.gz the power map is saved as a NIFTI file. Or if the extension is png/svg/pdf, it is saved as images. If None is passed then the image is shown on screen and the Matplotlib objects are returned.

  • sessions (list, optional) – List of session indices to be plot power maps for.

  • subtract_mean (bool, optional) – Should we subtract the mean power across modes?

  • mean_weights (np.ndarray, optional) – Numpy array with weightings for each mode to use to calculate the mean. Default is equal weighting.

  • plot_kwargs (dict, optional) –

    Keyword arguments to pass to nilearn.plotting.plot_img_on_surf.

osl_dynamics.analysis.power.independent_components_to_volumetric_maps(ica_spatial_maps, ic_values, output_file=None)[source]#

Independent components to volumetric spatial map.

Project the ic_values map to a brain map according to spatial maps of group ICA components. For example, ic_values can be the mean activation of states, or the rank-one decomposition of FC matrix corresponding to different states.

Parameters:

  • ica_spatial_maps (str or Nifti1Image) – Path to nifti file or nifti object containing the spatial maps obtained from group ICA. Should be in (n_x, n_y, n_z, n_voxels) format.

  • ic_values (np.ndarray) – Independent component values. Should be in (n_maps, n_ica_components) format.

  • output_file (str, optional) – Path to output file to save volumetric map to.

Returns:

vol_map – Volumetric maps. Shape is (n_x, n_y, n_z, n_maps).

Return type:

Nifti1Image

osl_dynamics.analysis.power.independent_components_to_surface_maps(ica_spatial_maps, ic_values, output_file=None)[source]#

Independent components to surface spatial map.

Project the ic_values map to a surface map according to spatial maps of group ICA components. For example, ic_values can be the mean activation of states, or the rank-one decomposition of FC matrix corresponding to different states.

Different from independent_components_to_volumetric_maps, this function works on CIFTI spatial maps.

Parameters:

  • ica_spatial_maps (str or Cifti2Image) – Path to cifti file or cifti object containing the spatial maps obtained from group ICA. Should be in (n_ica_components, n_voxels) format.

  • ic_values (np.ndarray) – Independent component values. Should be in (n_maps, n_ica_components) format.

  • output_file (str, optional) – Path to output file to save surface map to.

Returns:

surf_map – Surface map. Shape is (n_maps, n_voxels).

Return type:

Cifti2Image