osl_dynamics.utils.plotting#

Plotting functions.

Functions#

`set_style`(params)	Sets matplotlib's style.
`create_figure`(args, *kwargs)	Creates matplotlib figure and axes objects.
`show`([tight_layout])	Displays all figures in memory.
`save`(fig, filename[, tight_layout])	Save and close a figure.
`close`([fig])	Close a figure.
`rough_square_axes`(n_plots)	Get the most square axis layout for n_plots.
`get_colors`(n[, colormap])	Produce equidistant colors from a matplotlib colormap.
`plot_line`(x, y[, labels, legend_loc, errors, x_range, ...])	Basic line plot.
`plot_scatter`(x, y[, labels, legend_loc, errors, ...])	Basic scatter plot.
`plot_hist`(data, bins[, labels, legend_loc, x_range, ...])	Basic histogram plot.
`plot_bar_chart`(counts[, x, x_range, y_range, x_label, ...])	Bar chart plot.
`plot_gmm`(data, amplitudes, means, stddevs[, bins, ...])	Plot a two component Gaussian mixture model.
`plot_violin`(data[, x, x_label, y_label, title, ...])	Violin plot.
`plot_time_series`(time_series[, n_samples, ...])	Plot a time series with channel separation.
`plot_separate_time_series`(*time_series[, n_samples, ...])	Plot time series as separate subplots.
`plot_epoched_time_series`(data, time_index[, ...])	Plot continuous data, epoched and meant over epochs.
`plot_matrices`(matrix[, group_color_scale, titles, ...])	Plot a collection of matrices.
`plot_connections`(weights[, labels, ax, cmap, ...])	Create a chord diagram representing the values of a matrix.
`topoplot`(layout, data[, channel_names, plot_boxes, ...])	Make a contour plot in sensor space.
`plot_brain_surface`(values, mask_file, parcellation_file)	Plot a 2D heat map on the surface of the brain.
`plot_alpha`(*alpha[, n_samples, cmap, ...])	Plot alpha.
`plot_state_lifetimes`(state_time_course[, bins, ...])	Create a histogram of state lifetimes.
`plot_psd_topo`(f, psd[, only_show, parcellation_file, ...])	Plot PSDs for parcels and a topomap.
`plot_hmm_summary_stats`(fo, lt, intv, sr[, filename, ...])	Plot summary statistics (FO, LT, INTV, SR).
`plot_summary_stats_group_diff`(name, summary_stats, ...)	Plot summary statistics for two groups as violin plots.
`plot_evoked_response`(t, epochs, pvalues[, ...])	Plot an evoked responses with significant time points highlighted.
`plot_wavelet`(data, sampling_frequency[, w, ...])	Plot a wavelet transform.
`plot_design_matrix`(design[, show_contrasts, cmap, ax, ...])	Plot a GLM design matrix.

Module Contents#

osl_dynamics.utils.plotting.set_style(params)[source]#

Sets matplotlib’s style.

Wrapper for plt.rcParams.update. List of parameters can be found here.

Parameters:: params (dict) – Dictionary of style parameters to update.
Return type:: None

Examples

Make labels and linewidth larger:

plotting.set_style({
    "axes.labelsize": 16,
    "xtick.labelsize": 14,
    "ytick.labelsize": 14,
    "legend.fontsize": 14,
    "lines.linewidth": 3,
})

osl_dynamics.utils.plotting.create_figure(*args, **kwargs)[source]#

Creates matplotlib figure and axes objects.

Parameters:

fig_kwargs – Arguments to pass to plt.subplots.

Returns:

fig (plt.figure) – Matplotlib figure.
ax (array of plt.axes) – Array of axes (or single axis).

osl_dynamics.utils.plotting.show(tight_layout=False)[source]#

Displays all figures in memory.

Wrapper for plt.show.

Parameters:: tight_layout (bool, optional) – Should we call plt.tight_layout()?
Return type:: None

osl_dynamics.utils.plotting.save(fig, filename, tight_layout=False)[source]#

Save and close a figure.

Parameters:

fig (plt.figure) – Matplotlib figure object.
filename (str) – Output filename.
tight_layout (bool, optional) – Should we call fig.tight_layout()?

Return type:

None

osl_dynamics.utils.plotting.close(fig=None)[source]#

Close a figure.

Parameters:: fig (plt.figure, optional) – Figure to close. Defaults to all figures.
Return type:: None

osl_dynamics.utils.plotting.rough_square_axes(n_plots)[source]#

Get the most square axis layout for n_plots.

Given n_plots, find the side lengths of the rectangle which gives the closest layout to a square grid of axes.

Parameters:

n_plots (int) – Number of plots to arrange.

Returns:

short (int) – Number of axes on the short side.
long (int) – Number of axes on the long side.
empty (int) – Number of axes left blank from the rectangle.

Return type:

Tuple[int, int, int]

osl_dynamics.utils.plotting.get_colors(n, colormap='magma')[source]#

Produce equidistant colors from a matplotlib colormap.

Given a matplotlib colormap, produce a series of RGBA colors which are equally spaced by value. There is no guarantee that these colors will be perceptually uniformly distributed and with many colors will likely be extremely close.

Parameters:

n (int) – The number of colors to return.
colormap (str, optional) – The name of a matplotlib colormap.

Returns:

colors – Colors in RGBA format.

Return type:

list of tuple of float

Note

alpha=1.0 for all colors.

osl_dynamics.utils.plotting.plot_line(x, y, labels=None, legend_loc=1, errors=None, x_range=None, y_range=None, x_label=None, y_label=None, title=None, plot_kwargs=None, fig_kwargs=None, ax=None, filename=None)[source]#

Basic line plot.

Parameters:

x (list of np.ndarray) – x-ordinates.
y (list of np.ndarray) – y-ordinates.
labels (list of str, optional) – Legend labels for each line.
legend_loc (int, optional) – Matplotlib legend location identifier. Default is top right.
errors (list with 2 items, optional) – Min and max errors.
x_range (list, optional) – Minimum and maximum for x-axis.
y_range (list, optional) – Minimum and maximum for y-axis.
x_label (str, optional) – Label for x-axis.
y_label (str, optional) – Label for y-axis.
title (str, optional) – Figure title.
plot_kwargs (dict, optional) – Arguments to pass to the ax.plot method.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
ax (plt.axes, optional) – Axis object to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_scatter(x, y, labels=None, legend_loc=1, errors=None, x_range=None, y_range=None, x_label=None, y_label=None, title=None, markers=None, annotate=None, plot_kwargs=None, fig_kwargs=None, ax=None, filename=None)[source]#

Basic scatter plot.

Parameters:

x (list of np.ndarray) – x-ordinates.
y (list of np.ndarray) – y-ordinates.
labels (list of str, optional) – Legend labels for each line.
legend_loc (int, optional) – Matplotlib legend location identifier. Default is top right.
errors (list, optional) – Error bars.
x_range (list, optional) – Minimum and maximum for x-axis.
y_range (list, optional) – Minimum and maximum for y-axis.
x_label (str, optional) – Label for x-axis.
y_label (str, optional) – Label for y-axis.
title (str, optional) – Figure title.
markers (list of str, optional) – Markers to used for each set of data points.
annotate (List of array like objects, optional) – Annotation for each data point for each set of data points.
plot_kwargs (dict, optional) – Arguments to pass to the ax.scatter method.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
ax (plt.axes, optional) – Axis object to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_hist(data, bins, labels=None, legend_loc=1, x_range=None, y_range=None, x_label=None, y_label=None, title=None, plot_kwargs=None, fig_kwargs=None, ax=None, filename=None)[source]#

Basic histogram plot.

Parameters:

data (list of np.ndarray) – Raw data to plot (i.e. non-histogramed data).
bins (list of int) – Number of bins for each item in data.
labels (list of str, optional) – Legend labels for each line.
legend_loc (int, optional) – Matplotlib legend location identifier. Default is top right.
x_range (list, optional) – Minimum and maximum for x-axis.
y_range (list, optional) – Minimum and maximum for y-axis.
x_label (str, optional) – Label for x-axis.
y_label (str, optional) – Label for y-axis.
title (str, optional) – Figure title.
plot_kwargs (dict, optional) – Arguments to pass to the ax.hist method. Defaults to {"histtype": "step"}.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
ax (plt.axes, optional) – Axis object to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_bar_chart(counts, x=None, x_range=None, y_range=None, x_label=None, y_label=None, title=None, plot_kwargs=None, fig_kwargs=None, ax=None, filename=None)[source]#

Bar chart plot.

Parameters:

counts (list of np.ndarray) – Data to plot.
x (list or np.ndarray, optional) – x-values for counts.
x_range (list, optional) – Minimum and maximum for x-axis.
y_range (list, optional) – Minimum and maximum for y-axis.
x_label (str, optional) – Label for x-axis.
y_label (str, optional) – Label for y-axis.
title (str, optional) – Figure title.
plot_kwargs (dict, optional) – Arguments to pass to the ax.bar method.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
ax (plt.axes, optional) – Axis object to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_gmm(data, amplitudes, means, stddevs, bins=50, legend_loc=1, x_range=None, y_range=None, x_label=None, y_label=None, title=None, fig_kwargs=None, ax=None, filename=None)[source]#

Plot a two component Gaussian mixture model.

Parameters:

data (np.ndarray) – Raw data to plot as a histogram.
amplitudes (np.ndarray) – Amplitudes of each Gaussian component. Mixture weights scaled by mixture covariances.
means (np.ndarray) – Mean of each Gaussian component.
stddevs (np.ndarray) – Standard deviation of each Gaussian component.
bins (list of int, optional) – Number of bins for the histogram.
legend_loc (int, optional) – Position for the legend.
x_range (list, optional) – Minimum and maximum for x-axis.
y_range (list, optional) – Minimum and maximum for y-axis.
x_label (str, optional) – Label for x-axis.
y_label (str, optional) – Label for y-axis.
title (str, optional) – Figure title.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
ax (plt.axes, optional) – Axis object to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_violin(data, x=None, x_label=None, y_label=None, title=None, fig_kwargs=None, sns_kwargs=None, ax=None, filename=None)[source]#

Violin plot.

Parameters:

data (list of np.ndarray) – Data to plot.
x (list or np.ndarray, optional) – x-values for data.
x_label (str, optional) – Label for x-axis.
y_label (str, optional) – Label for y-axis.
title (str, optional) – Figure title.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
sns_kwargs (dict, optional) – Arguments to pass to sns.violinplot().
ax (matplotlib.axes.axes, optional) – Axis object to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_time_series(time_series, n_samples=None, y_tick_values=None, plot_kwargs=None, fig_kwargs=None, ax=None, filename=None)[source]#

Plot a time series with channel separation.

Parameters:

time_series (np.ndarray) – The time series to be plotted. Shape must be (n_samples, n_channels).
n_samples (int, optional) – The number of time points to be plotted.
y_tick_values (, optional) – Labels for the channels to be placed on the y-axis.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
plot_kwargs (dict, optional) –
Keyword arguments to be passed on to ax.plot. Defaults to {"lw": 0.7, "color": "tab:blue"}.
ax (plt.axes, optional) – The axis on which to plot the data. If not given, a new axis is created.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_separate_time_series(*time_series, n_samples=None, sampling_frequency=None, fig_kwargs=None, plot_kwargs=None, filename=None)[source]#

Plot time series as separate subplots.

Parameters:

time_series (np.ndarray) – Time series to be plotted. Should be (n_samples, n_lines). Each line is its own subplot.
sampling_frequency (float, optional) – Sampling frequency of the input data, enabling us to label the x-axis.
n_samples (int, optional) – Number of samples to be shown on the x-axis.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
plot_kwargs (dict, optional) –
Keyword arguments to be passed on to ax.plot. Defaults to {"lw": 0.7}.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_epoched_time_series(data, time_index, sampling_frequency=None, pre=125, post=1000, baseline_correct=False, legend=True, legend_loc=1, title=None, plot_kwargs=None, fig_kwargs=None, ax=None, filename=None)[source]#

Plot continuous data, epoched and meant over epochs.

Parameters:

data (np.ndarray) – Data to be epoched. Shape must be (n_samples, n_channels).
time_index (np.ndarray) – The integer indices of the start of each epoch.
sampling_frequency (float, optional) – The sampling frequency of the data in Hz.
pre (int, optional) – The integer number of samples to include before the trigger.
post (int, optional) – The integer number of samples to include after the trigger.
baseline_correct (bool, optional) – Should we subtract the mean value pre-trigger.
legend (bool, optional) – Should a legend be created.
legend_loc (int, optional) – Location of the legend.
title (str, optional) – Title of the figure.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
plot_kwargs (dict, optional) –
Keyword arguments to be passed on to ax.plot.
ax (plt.axes, optional) – The axis on which to plot the data. If not given, a new axis is created.
filename (str, optional) – Output_filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_matrices(matrix, group_color_scale=True, titles=None, main_title=None, cmap='viridis', nan_color='white', log_norm=False, filename=None)[source]#

Plot a collection of matrices.

Given an iterable of matrices, plot each matrix in its own axis. The axes are arranged as close to a square (N x N axis grid) as possible.

Parameters:

matrix (list of np.ndarray) – The matrices to plot.
group_color_scale (bool, optional) – If True, all matrices will have the same colormap scale, where we use the minimum and maximum across all matrices as the scale.
titles (list of str, optional) – Titles to give to each matrix axis.
main_title (str, optional) – Main title to be placed at the top of the plot.
cmap (str or matplotlib.colors.ListedColormap, optional) – Matplotlib colormap.
nan_color (str, optional) – Matplotlib color to use for NaN values.
log_norm (bool, optional) – Should we show the elements on a log scale?
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if filename=None.

osl_dynamics.utils.plotting.plot_connections(weights, labels=None, ax=None, cmap='hot', text_color=None, filename=None)[source]#

Create a chord diagram representing the values of a matrix.

For a matrix of weights, create a chord diagram where the color of the line connecting two nodes represents the value indexed by the position of the nodes in the lower triangle of the matrix.

This is useful for showing things like co-activation between sensors/parcels or relations between nodes in a network.

Parameters:

weights (np.ndarray) – An NxN matrix of weights.
labels (list of str, optional) – A name for each node in the weights matrix (e.g. parcel names)
ax (plt.axes, optional) – A matplotlib axis on which to plot.
cmap (str or matplotlib.colors.ListedColormap, optional) – Matplotlib colormap.
text_color (str, optional) – A string corresponding to a matplotlib color.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.topoplot(layout, data, channel_names=None, plot_boxes=False, show_deleted_sensors=False, show_names=False, title=None, colorbar=True, axis=None, cmap='cold_hot', n_contours=10, filename=None)[source]#

Make a contour plot in sensor space.

Create a contour plot by interpolating a field from a set of values provided for each sensor location in an MEG layout. Within the context of DyNeMo this is likely to be an array of (all positive) values taken from the diagonal of a covariance matrix, but one can also plot any sensor level M/EEG data.

Parameters:

layout (str) – The name of an MEG layout (matching one from FieldTrip).
data (np.ndarray) – The value of the field at each sensor.
channel_names (list of str, optional) – A list of channel names which are present in the data (removes missing channels).
plot_boxes (bool, optional) – Show boxes representing the height and width of sensors.
show_deleted_sensors (bool, optional) – Show sensors missing from channel_names in red.
show_names (bool, optional) – Show the names of channels (can get very cluttered).
title (str, optional) – A title for the figure.
colorbar (bool, optional) – Show a colorbar for the field.
axis (plt.axis, optional) – matplotlib axis to plot on.
cmap (str or matplotlib.colors.ListedColormap, optional) – Matplotlib colormap.
n_contours (int, optional) – number of field isolines to show on the plot.
filename (str, optional) – Output filename.

Returns:

fig – Matplotlib figure object. Only returned if ax=None and filename=None.

Return type:

plt.figure

osl_dynamics.utils.plotting.plot_brain_surface(values, mask_file, parcellation_file, title=None, cmap='cold_hot', colorbar=True, symmetric_cbar=True, cbar_tick_format='%.2g', cbar_fontsize=24, cbar_label=None, vmin=None, vmax=None, hemispheres=None, views=None, bg_on_data=False, threshold=None, remove_subcortical_voxels=False, filename=None, show_plot=None)[source]#

Plot a 2D heat map on the surface of the brain.

Parameters:

values (np.ndarray) – Data to plot. Must be of shape (n_parcels,).
mask_file (str) – Mask file for the brain. See osl_dynamics.files.mask.
parcellation_file (str) – Parcellation file. See osl_dynamics.files.parcellation.
title (str, optional) – Title for the plot.
cmap (str or matplotlib.colors.ListedColormap, optional) – Matplotlib colormap.
colorbar (bool, optional) – Should we plot a colorbar?
symmetric_cbar (bool, optional) – Should we have a symmetric color bar?
cbar_tick_format (str, optional) – Formatting for the color bar tick labels. Example use: cbar_tick_format='%.2f'.
cbar_fontsize (int, optional) – Fontsize for the color bar ticks and label.
cbar_label (str, optional) – Label for the color bar.
vmin (float, optional) – Minimum value for the color bar. May be overridden if symmetric_cbar=True.
vmax (float, optional) – Maximum value for the color bar. May be overridden if symmetric_cbar=True.
hemispheres (list, optional) – ['left', 'right'] or ['left'] or ['right']. Defaults to ['left', 'right'].
views (list, optional) – The list can contain 'lateral' or 'medial'. Defaults to ['lateral'], which will show one row with lateral views. ['lateral', 'medial'] will show two rows with the lateral view on top and medial view below.
bg_on_data (bool, optional) – If True, the sulcal depth is jointly visible with surface data. Otherwise, the background image will only be visible where there is no surface data (either because the surface data contains nans or because is was thresholded).
threshold (float, optional) – Threshold values to display. Defaults to no thresholding.
remove_subcortical_voxels (bool, optional) – Should we set the subcortical voxels to np.nan?
filename (str, optional) – Output filename. Extension can be png/svg/pdf. If None is passed then the image is shown on screen and the Matplotlib objects are returned.
show_plot (bool, optional) – Should we show the plot? If filename is True, defaults to False, otherwise False.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if filename is None.
ax (plt.axes) – Matplotlib axis object. Only returned if filename is None.

osl_dynamics.utils.plotting.plot_alpha(*alpha, n_samples=None, cmap='tab10', sampling_frequency=None, y_labels=None, title=None, plot_kwargs=None, fig_kwargs=None, filename=None, axes=None)[source]#

Plot alpha.

Parameters:

alpha (np.ndarray) – A collection of alphas passed as separate arguments.
n_samples (int, optional) – Number of time points to be plotted.
cmap (str or matplotlib.colors.ListedColormap, optional) – Matplotlib colormap.
sampling_frequency (float, optional) – The sampling frequency of the data in Hz.
y_labels (str, optional) – Labels for the y-axis of each alpha time series.
title (str, optional) – Title for the plot.
plot_kwargs (dict, optional) – Any parameters to be passed to plt.stackplot.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
filename (str, optional) – Output filename.
axes (list of plt.axes, optional) – A list of matplotlib axes to plot on. If None, a new figure is created.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_state_lifetimes(state_time_course, bins='auto', density=False, match_scale_x=False, match_scale_y=False, x_range=None, x_label=None, y_label=None, plot_kwargs=None, fig_kwargs=None, filename=None)[source]#

Create a histogram of state lifetimes.

For a state time course, create a histogram for each state with the distribution of the lengths of time for which it is active.

Parameters:

state_time_course (np.ndarray) – Mode time course to analyse.
bins (int, optional) – Number of bins for the histograms.
density (bool, optional) – If True, plot the probability density of the state activation lengths. If False, raw number.
match_scale_x (bool, optional) – If True, all histograms will share the same x-axis scale.
match_scale_y (bool, optional) – If True, all histograms will share the same y-axis scale.
x_range (list, optional) – The limits on the values presented on the x-axis.
x_label (str, optional) – x-axis label.
y_label (str, optional) – y-axis label.
plot_kwargs (dict, optional) –
Keyword arguments to pass to ax.hist.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_psd_topo(f, psd, only_show=None, parcellation_file=None, frequency_range=None, topomap_pos=None, cmap='viridis', fig_kwargs=None, ax=None, filename=None)[source]#

Plot PSDs for parcels and a topomap.

Parameters:

f (np.ndarray) – Frequency axis. Shape must be (n_freq,).
psd (np.ndarray) – PSD for each parcel. Shape must be (n_parcels, n_freq).
only_show (list, optional) – Indices for parcels to include in the plot. Defaults to all parcels.
parcellation_file (str, optional) – Path to parcellation file.
frequency_range (list, optional) – Min and max frequency for the x-axis.
topomap_pos (list, optional) – Positioning and size of the topomap: [x0, y0, width, height]. x0, y0, width, height should be floats between 0 and 1. Defaults to [0.45, 0.55, 0.5, 0.55] to place the topomap on the top right. This is not used if parcellation_file=None.
cmap (str, optional) – Matplotlib colormap.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
ax (matplotlib Axis, optional) – Axis to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_hmm_summary_stats(fo, lt, intv, sr, filename=None, cmap='tab10', fig_kwargs=None, sns_kwargs=None)[source]#

Plot summary statistics (FO, LT, INTV, SR).

Parameters:

fo (np.ndarray) – Fractional occupancies. Shape must be (n_subjects, n_states).
lt (np.ndarray) – Mean lifetimes in seconds. Shape must be (n_subjects, n_states).
intv (np.ndarray) – Mean intervals in seconds. Shape must be (n_subjects, n_states).
sr (np.ndarray) – Switching rates in Hz. Shape must be (n_subjects, n_states).
filename (str, optional) – Output filename.
cmap (str, optional) – Matplotlib colormap.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
sns_kwargs (dict, optional) – Arguments to pass to sns.violinplot().

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_summary_stats_group_diff(name, summary_stats, pvalues, assignments, fig_kwargs=None, ax=None, filename=None)[source]#

Plot summary statistics for two groups as violin plots.

Parameters:

name (str) – Name of the summary statistic.
summary_stats (np.ndarray) – Summary statistics. Shape is (n_sessions, n_states).
pvalues (np.ndarray) – p-values for each summary statistic difference. Shape is (n_states,).
assignments (np.ndarray) – Array of 1s and 2s indicating group assignment. Shape is (n_sessions,).
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
ax (plt.axes, optional) – Axis object to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_evoked_response(t, epochs, pvalues, significance_level=0.05, offset_between_bars=0.01, labels=None, legend_loc=1, x_label=None, y_label=None, title=None, fig_kwargs=None, ax=None, filename=None)[source]#

Plot an evoked responses with significant time points highlighted.

Parameters:

t (np.ndarray) – Time axis. Shape must be (n_samples,).
epochs (np.ndarray) – Evoked responses. Shape must be (n_samples, n_channels).
pvalues (np.ndarray) – p-value for each evoked response. This can be calculated with osl_dynamics.analysis.statistics.evoked_response_max_stat_perm().
significance_level (float, optional) – Value to threshold the p-values with to consider significant. By default pvalues < 0.05 are significant.
offset_between_bars (float, optional) – Vertical offset between bars that highlight significance.
labels (list, optional) – Label for each evoked response time series.
legend_loc (int, optional) – Position of the legend.
x_label (str, optional) – Label for x-axis.
y_label (str, optional) – Label for y-axis.
title (str, optional) – Figure title.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
ax (plt.axes, optional) – Axis object to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_wavelet(data, sampling_frequency, w=5, standardize=True, time_range=None, frequency_range=None, title=None, add_colorbar=True, fig_kwargs=None, plot_kwargs=None, ax=None, filename=None)[source]#

Plot a wavelet transform.

Parameters:

data (np.ndarray) – 1D time series data.
sampling_frequency (float) – Sampling frequency in Hz.
w (float, optional) – w parameter to pass to scipy.signal.morlet2.
standardize (bool, optional) – Should we standardize the data before calculating the wavelet?
time_range (list, optional) – Start time and end time to plot in seconds. Default is the full time axis of the data.
frequency_range (list of length 2, optional) – Start and end frequency to plot in Hz. Default is [1, sampling_frequency / 2].
title (str, optional) – Figure title.
add_colorbar (bool, optional) – If True (default), space will be stolen from the figure to create a colorbar.
fig_kwargs (dict, optional) – Arguments to pass to plt.subplots().
plot_kwargs (dict, optional) – Keyword arguments to pass to ax.pcolormesh. Defaults to {"cmap": "rainbow"}.
ax (plt.axes, optional) – Axis object to plot on.
filename (str, optional) – Output filename.

Returns:

fig (plt.figure) – Matplotlib figure object. Only returned if ax=None and filename=None.
ax (plt.axes) – Matplotlib axis object(s). Only returned if ax=None and filename=None.

osl_dynamics.utils.plotting.plot_design_matrix(design, show_contrasts=True, cmap='coolwarm', ax=None, filename=None)[source]#

Plot a GLM design matrix.

Displays the design matrix as a heatmap with feature names as column labels and a diverging colormap centred at zero.

Parameters:

design (osl_dynamics.glm.base.Design) – Design object.
show_contrasts (bool, optional) – If True, display the contrast matrix below the design matrix.
cmap (str, optional) – Matplotlib colormap name.
ax (plt.Axes, optional) – Axis to plot on. If None, a new figure is created. Cannot be used with show_contrasts=True.
filename (str, optional) – Output filename. If None, the figure and axes are returned.

Returns:

fig (plt.Figure) – Matplotlib figure. Only returned if ax=None and filename=None.
axes (plt.Axes or np.ndarray of plt.Axes) – Matplotlib axes. Only returned if ax=None and filename=None.