glhmm.graphics

Basic graphics - Gaussian Linear Hidden Markov Model @author: Diego Vidaurre 2023

glhmm.graphics.blue_colormap()

Generate a custom blue colormap.

Returns:

A custom colormap with shades of blue.

glhmm.graphics.create_cmap_alpha(cmap_list, color_array, alpha)

Modify the colors in a colormap based on an alpha threshold.

Parameters:

cmap_list (numpy.ndarray)

List of colors representing the original colormap.

color_array (numpy.ndarray)

Array of color values corresponding to each colormap entry.

alpha (float)

Alpha threshold for modifying colors.

Returns:

Modified list of colors representing the colormap with adjusted alpha values.

glhmm.graphics.custom_colormap()

Generate a custom colormap consisting of segments from red to blue.

Returns:

A custom colormap with defined color segments.

glhmm.graphics.interpolate_colormap(cmap_list)

Create a new colormap with the modified color_array.

Parameters:

cmap_list (numpy.ndarray):

Original color array for the colormap.

Returns:

modified_cmap (numpy.ndarray):

Modified colormap array.

glhmm.graphics.plot_FO(FO, figsize=(8, 4), fontsize_labels=13, fontsize_title=16, width=0.8, xlabel='Subject', ylabel='Fractional occupancy', title='State Fractional Occupancies', show_legend=True, num_ticks=10)

Plot fractional occupancies for different states.

Parameters:

FO (numpy.ndarray):

Fractional occupancy data matrix.

figsize (tuple, optional), default=(8,4):

Figure size.

fontsize_labels (int, optional), default=13:

Font size for axes labels.

fontsize_title (int, optional), default=16:

Font size for plot title.

width (float, optional), default=0.5:

Width of the bars.

xlabel (str, optional), default=’Subject’:

Label for the x-axesis.

ylabel (str, optional), default=’Fractional occupancy’:

Label for the y-axesis.

title (str, optional), default=’State Fractional Occupancies’:

Title for the plot.

show_legend (bool, optional), default=True:

Whether to show the legend.

glhmm.graphics.plot_average_probability(Gamma_reconstruct, title='Average probability for each state', fontsize=16, figsize=(7, 5), vertical_lines=None, line_colors=None, highlight_boxes=False)

Plots the average probability for each state over time.

Parameters:

Gamma_reconstruct (numpy.ndarray)

3D array representing reconstructed gamma values. Shape: (num_timepoints, num_trials, num_states)

title (str, optional), default=’Average probability for each state’:

Title for the plot.

fontsize (int, optional), default=16:

Font size for labels and title.

figsize (tuple, optional), default=(8,6):

Figure size (width, height) in inches).

vertical_lines (list of tuples, optional), default=None:

List of pairs specifying indices for vertical lines.

line_colors (list of str or bool, optional), default=None:

List of colors for each pair of vertical lines. If True, generates random colors (unless a list is provided).

highlight_boxes (bool, optional), default=False:

Whether to include highlighted boxes for each pair of vertical lines.

glhmm.graphics.plot_condition_difference(Gamma_reconstruct, R_trials, title='Average Probability and Difference', fontsize=16, figsize=(9, 2), vertical_lines=None, line_colors=None, highlight_boxes=False)

Plots the average probability for each state over time for two conditions and their difference.

Parameters:

Gamma_reconstruct (numpy.ndarray)

3D array representing reconstructed gamma values. Shape: (num_timepoints, num_trials, num_states)

R_trials (numpy.ndarray)

1D array representing the condition for each trial. Should have the same length as the second dimension of Gamma_reconstruct.

title (str, optional), default=’Average Probability and Difference’:

Title for the plot.

fontsize (int, optional), default=16:

Font size for labels and title.

figsize (tuple, optional), default=(9, 2):

Figure size (width, height).

vertical_lines (list of tuples, optional), default=None:

List of pairs specifying indices for vertical lines.

line_colors (list of str or bool, optional), default=None:

List of colors for each pair of vertical lines. If True, generates random colors (unless a list is provided).

highlight_boxes (bool, optional), default=False:

Whether to include highlighted boxes for each pair of vertical lines.

Example usage:

plot_condition_difference(Gamma_reconstruct, R_trials, vertical_lines=[(10, 100)], highlight_boxes=True)

glhmm.graphics.plot_correlation_matrix(corr_vals, performed_tests, normalize_vals=False, figsize=(9, 5), title_text='Correlation Coefficients Heatmap', annot=False, cmap_type='default', cmap_reverse=True, xlabel='', ylabel='', xticklabels=None, xlabel_rotation=45, none_diagonal=False, num_colors=256)

glhmm.graphics.plot_p_value_matrix(pval, alpha=0.05, normalize_vals=True, figsize=(9, 5), title_text='Heatmap (p-values)', annot=False, cmap_type='default', cmap_reverse=True, xlabel='', ylabel='', xticklabels=None, none_diagonal=False, num_colors=259, xlabel_rotation=0)

glhmm.graphics.plot_p_values_bar(pval, xticklabels=[], figsize=(9, 4), num_colors=256, xlabel='', ylabel='P-values (Log Scale)', title_text='Bar Plot', tick_positions=[0, 0.001, 0.01, 0.05, 0.1, 0.3, 1], top_adjustment=0.9, alpha=0.05, pad_title=20, xlabel_rotation=45, pval_text_hight_same=False)

Visualize a bar plot with LogNorm and a colorbar.

Parameters:

pval (numpy.ndarray):

Array of p-values to be plotted.

xticklabels (list, optional), default=[]:

List of categories or variables.

figsize (tuple, optional), default=(9, 4):

Figure size in inches (width, height).

num_colors (int, optional), default=256:

Number of colors in the colormap.

xlabel (str, optional), default=””:

X-axis label.

ylabel (str, optional), default=”P-values (Log Scale)”:

Y-axis label.

title_text (str, optional), default=”Bar Plot”:

Title for the plot.

tick_positions (list, optional), default=[0, 0.001, 0.01, 0.05, 0.1, 0.3, 1]

Positions of ticks on the colorbar.

top_adjustment (float, optional), default=0.9:

Adjustment for extra space between title and plot.

alpha (float, optional), default=0.05:

Alpha value is the threshold we set for the p-values when doing visualization.

pad_title (int, optional), default=20:

Padding for the plot title.

glhmm.graphics.plot_p_values_over_time(pval, figsize=(8, 4), total_time_seconds=None, xlabel='Timepoints', ylabel='P-values (Log Scale)', title_text='P-values over time', xlim_start=0, tick_positions=[0, 0.001, 0.01, 0.05, 0.1, 0.3, 1], num_colors=259, alpha=0.05, plot_style='line', linewidth=2.5)

Plot a scatter plot of p-values over time with a log-scale y-axis and a colorbar.

Parameters:

pval (numpy.ndarray):

The p-values data to be plotted.

figsizetuple, optional, default=(8, 4):

Figure size in inches (width, height).

total_time_secondsfloat, optional, default=None

Total time duration in seconds. If provided, time points will be scaled accordingly.

xlabel (str, optional), default=”Timepoints”:

Label for the x-axis.

ylabel (str, optional), default=”P-values (Log Scale)”:

Label for the y-axis.

title_text (str, optional), default=”P-values over time”:

Title for the plot.

xlim_start (int, optional), default=0:

Starting point for the x-axis limit.

tick_positions (list, optional), default=[0, 0.001, 0.01, 0.05, 0.1, 0.3, 1]:

Specific values to mark on the y-axis.

num_colors (int, optional), default=259:

Resolution for the color bar.

alpha (float, optional), default=0.05:

Alpha value is the threshold we set for the p-values when doing visualization.

plot_style (str, optional), default=”line”:

Style of plot.

linewidth (float, optional), default=2.5:

Width of the lines in the plot.

glhmm.graphics.plot_permutation_distribution(test_statistic, title_text='Permutation Distribution', xlabel='Test Statistic Values', ylabel='Density')

Plot the histogram of the permutation with the observed statistic marked.

Parameters:

test_statistic (numpy.ndarray)

An array containing the permutation values.

title_text (str, optional), default=”Permutation Distribution”:

Title text of the plot.

xlabel (str, optional), default=”Test Statistic Values”

Text of the xlabel.

ylabel (str, optional), default=”Density”

Text of the ylabel.

glhmm.graphics.plot_scatter_with_labels(p_values, alpha=0.05, title_text='', xlabel=None, ylabel=None, xlim_start=0.9, ylim_start=0)

Create a scatter plot to visualize p-values with labels indicating significant points.

Parameters:

p_values (numpy.ndarray)

An array of p-values. Can be a 1D array or a 2D array with shape (1, 5).

alpha (float, optional), default=0.05:

Threshold for significance.

title_text (str, optional), default=””:

The title text for the plot.

xlabel (str, optional), default=None:

The label for the x-axis.

ylabel (str, optional), default=None:

The label for the y-axis.

xlim_start (float, optional), default=-5

Start position of x-axis limits.

ylim_start (float, optional), default=-0.1

Start position of y-axis limits.

Notes:

Points with p-values less than alpha are considered significant and marked with red text.

glhmm.graphics.plot_state_lifetimes(LT, figsize=(8, 4), fontsize_labels=13, fontsize_title=16, width=0.18, xlabel='Subject', ylabel='Lifetime', title='State Lifetimes', show_legend=True, num_ticks=10)

Plot state lifetimes for different states.

Parameters:

LT (numpy.ndarray):

State lifetime (dwell time) data matrix.

figsize (tuple, optional), default=(8, 4):

Figure size.

fontsize_labels (int, optional), default=13:

Font size for axeses labels.

fontsize_title (int, optional), default=16:

Font size for plot title.

width (float, optional), default=0.18:

Width of the bars.

xlabel (str, optional), default=’Subject’:

Label for the x-axesis.

ylabel (str, optional), default=’Lifetime’:

Label for the y-axesis.

title (str, optional), default=’State Lifetimes’:

Title for the plot.

show_legend (bool, optional), default=True:

Whether to show the legend.

glhmm.graphics.plot_state_prob_and_covariance(init_stateP, TP, state_means, state_FC, cmap='viridis', figsize=(9, 7), num_ticks=5)

Plot HMM parameters.

Parameters:

init_stateParray-like

Initial state probabilities.

TParray-like

Transition probabilities.

state_meansarray-like

State means.

state_FCarray-like

State covariances.

cmapstr or Colormap, optional

The colormap to be used for plotting. Default is ‘viridis’.

figsizetuple, optional

Figure size. Default is (9, 7).

num_ticksint, optional

Number of ticks for the colorbars

glhmm.graphics.plot_switching_rates(SR, figsize=(8, 4), fontsize_labels=13, fontsize_title=16, width=0.18, xlabel='Subject', ylabel='Switching Rate', title='State Switching Rates', show_legend=True, num_ticks=10)

Plot switching rates for different states.

Parameters:

SR (numpy.ndarray):

Switching rate data matrix.

figsize (tuple, optional), default=(8, 4):

Figure size.

fontsize_labels (int, optional), default=13:

Font size for axes labels.

fontsize_title (int, optional), default=16:

Font size for plot title.

width (float, optional), default=0.18:

Width of the bars.

xlabel (str, optional), default=’Subject’:

Label for the x-axesis.

ylabel (str, optional), default=’Switching Rate’:

Label for the y-axesis.

title (str, optional), default=’State Switching Rates’:

Title for the plot.

show_legend (bool, optional), default=True:

Whether to show the legend.

glhmm.graphics.plot_vpath(viterbi_path, signal=None, idx_data=None, figsize=(7, 4), fontsize_labels=13, fontsize_title=16, yticks=None, time_conversion_rate=None, xlabel='Timepoints', ylabel='', title='Viterbi Path', signal_label='Signal', show_legend=True, vertical_linewidth=1.5)

Plot Viterbi path with optional signal overlay.

Parameters:

viterbi_path

The Viterbi path data matrix.

signalarray-like, optional

Signal data to overlay on the plot. Default is None.

idx_dataarray-like, optional

Array representing time intervals. Default is None.

figsizetuple, optional

Figure size. Default is (7, 4).

fontsize_labelsint, optional

Font size for axis labels. Default is 13.

fontsize_titleint, optional

Font size for plot title. Default is 16.

yticksbool, optional

Whether to show y-axis ticks. Default is None.

time_conversion_ratefloat, optional

Conversion rate from time steps to seconds. Default is None.

xlabelstr, optional

Label for the x-axis. Default is “Timepoints”.

ylabelstr, optional

Label for the y-axis. Default is “”.

titlestr, optional

Title for the plot. Default is “Viterbi Path”.

signal_labelstr, optional

Label for the signal plot. Default is “Signal”.

show_legendbool, optional

Whether to show the legend. Default is True.

vertical_linewidthfloat, optional

Line width for vertical gray lines. Default is 1.5.

glhmm.graphics.red_colormap()

Generate a custom colormap consisting of red and warm colors.

Returns:

A custom colormap with red and warm color segments.

glhmm.graphics.show_Gamma(Gamma, line_overlay=None, tlim=None, Hz=1, palette='viridis')

Displays the activity of the hidden states as a function of time.

Parameters:

Gammaarray of shape (n_samples, n_states)

The state timeseries probabilities.

line_overlayarray of shape (n_samples, 1)

A secondary related data type to overlay as a line.

tlim2x1 array or None, default=None

The time interval to be displayed. If None (default), displays the entire sequence.

Hzint, default=1

The frequency of the signal, in Hz.

palettestr, default = ‘Oranges’

The name of the color palette to use.

glhmm.graphics.show_beta(hmm, only_active_states=True, recompute_states=False, X=None, Y=None, Gamma=None, show_average=None, alpha=1.0)

Displays the beta coefficients of a given HMM. The beta coefficients can be extracted directly from the HMM structure or reestimated from the data; for the latter, X, Y and Gamma need to be provided as parameters. This is useful for example if one has run the model on PCA space, but wants to show coefficients in the original space.

Parameters:

hmm: HMM object

An instance of the HMM class containing the beta coefficients to be visualized.

only_active_states: bool, optional, default=False

If True, only the beta coefficients of active states are shown.

recompute_states: bool, optional, default=False

If True, the betas will be recomputed from the data and the state time courses

X: numpy.ndarray, optional, default=None

The timeseries of set of variables 1.

Y: numpy.ndarray, optional, default=None

The timeseries of set of variables 2.

Gamma: numpy.ndarray, optional, default=None

The state time courses

show_average: bool, optional, default=None

If True, an additional row of the average beta coefficients is shown.

alpha: float, optional, default=0.1

The regularisation parameter to be applied if the betas are to be recomputed.

glhmm.graphics.show_temporal_statistic(Gamma, indices, statistic='FO', type_plot='barplot')

Plots a statistic over time for a set of sessions.

Parameters:

Gammaarray of shape (n_samples, n_states)

The state timeseries probabilities.

indices: numpy.ndarray of shape (n_sessions,)

The session indices to plot.

statistic: str, default=’FO’

The statistic to compute and plot. Can be ‘FO’, ‘switching_rate’ or ‘FO_entropy’.

type_plot: str, default=’barplot’

The type of plot to generate. Can be ‘barplot’, ‘boxplot’ or ‘matrix’.

Raises:

Exception

• Statistic is not one of ‘FO’, ‘switching_rate’ or ‘FO_entropy’.

• type_plot is ‘boxplot’ and there are less than 10 sessions.

• type_plot is ‘matrix’ and there is only one session.

glhmm.graphics.show_trans_prob_mat(hmm, only_active_states=False, show_diag=True, show_colorbar=True)

Displays the transition probability matrix of a given HMM.

Parameters:

hmm: HMM object

An instance of the HMM class containing the transition probability matrix to be visualized.

only_active_statesbool, optional, default=False

Whether to display only active states or all states in the matrix.

show_diagbool, optional, defatult=True

Whether to display the diagonal elements of the matrix or not.

show_colorbarbool, optional, default=True

Whether to display the colorbar next to the matrix or not.