glhmm.statistics

Permutation testing from Gaussian Linear Hidden Markov Model @author: Nick Y. Larsen 2023

glhmm.statistics.calculate_anova_f_test(Din, Rin, idx_data=None, permute_beta=False, perm=0, nan_values=False, beta=None, no_t_stats=False, Nnull_samples=False, method=None)

Calculate the f-test values for the regression of each dependent variable in Rin on the independent variables in Din, while handling NaN values column-wise.

Parameters:

Din (numpy.ndarray):

Input data matrix for the independent variables.

Rin (numpy.ndarray):

Input data matrix for the dependent variables.

idx_data (numpy.ndarray):

Marks the indices for each trial within the session. It is a 2D array where each row represents the start and end index for a session.

permute_beta (bool, optional):

A flag indicating whether to permute beta coefficients.

perm (int):

The permutation index.

nan_values (bool, optional), default=False::

A flag indicating whether there are NaN values.

beta (numpy.ndarray):

Returns:

R2_test (numpy.ndarray): Array of f-test values for each regression.

glhmm.statistics.calculate_baseline_difference(vpath_array, R_data, state, comparison_statistic, state_comparison)

Calculate the difference between the specified statistics of a state and all other states combined.

Parameters:

vpath_data (numpy.ndarray):

The Viterbi path as of integer values that range from 1 to n_states.

R_data (numpy.ndarray):

The dependent-variable associated with each state.

state(numpy.ndarray):

The state for which the difference is calculated from.

comparison_statistic (str)

The chosen statistic to be calculated. Valid options are “mean” or “median”.

Returns:

difference (float)

The calculated difference between the specified state and all other states combined.

glhmm.statistics.calculate_beta_session(reg_pinv, Rin, Din, test_indices_list, train_indices_list)

Calculate beta coefficients for each session. If there are NaN values the procedure will be done per column.

Parameters:

reg_pinv (numpy.ndarray):

The regularized pseudo-inverse of D_data.

Rin (numpy.ndarray):

Input data matrix for the dependent variables.

idx_data (numpy.ndarray):

Marks the indices for each trial within the session. It is a 2D array where each row represents the start and end index for a session.

permute_beta (bool, optional), default=False:

A flag indicating whether to permute beta coefficients.

category_limitint or None, optional, default=10

Maximum allowed number of categories for F-test. Acts as a safety measure for columns with integer values, like age, which may be mistakenly identified as multiple categories.

glhmm.statistics.calculate_combined_z_scores(p_values, combine_tests=None)

Calculate test statistics of z-scores converted from p-values based on the specified combination.

Parameters:

p_values (numpy.ndarray):

Matrix of p-values.

combine_tests (str):

Specifies the combination method. Valid options: “True”, “across_columns”, “across_rows”. Default is “True”.

Returns:

result (numpy.ndarray):

Test statistics of z-scores converted from p-values.

glhmm.statistics.calculate_correlation_and_tstats(Din, Rin, pval_parametric=False)

Calculates Pearson correlation coefficients and t-statistics for each pair of columns between Din and Rin. Optionally calculates p-values.

Parameters:

Din (numpy.ndarray):

Input data vector or matrix with shape (n_samples, n_predictors).

Rin (numpy.ndarray):

Input data vector or matrix with shape (n_samples, n_targets).

pval_parametric (bool, optional):

If True, calculates parametric p-values. Default is False.

Returns:

correlation_matrix (numpy.ndarray or float):

Pearson correlation coefficient(s) for each predictor-target pair.

t_statistics (numpy.ndarray or float):

t-statistic(s) for each predictor-target pair, computed from the correlation coefficients.

pval_matrix (numpy.ndarray or float, optional):

Only returned if pval_parametric=True. Permutation-based p-values for each predictor-target pair.

glhmm.statistics.calculate_manova_f_test(Din, Rin, nan_values, no_t_stats=False)

Calculate the f-test values for the regression of each dependent variable in Rin on the independent variables in Din, while handling NaN values column-wise.

Parameters:

Din (numpy.ndarray):

Input data matrix for the independent variables.

Rin (numpy.ndarray):

Input data matrix for the dependent variables.

idx_data (numpy.ndarray):

Marks the indices for each trial within the session. It is a 2D array where each row represents the start and end index for a session.

permute_beta (bool, optional):

A flag indicating whether to permute beta coefficients.

perm (int):

The permutation index.

nan_values (bool, optional), default=False::

A flag indicating whether there are NaN values.

beta (numpy.ndarray):

Returns:

R2_test (numpy.ndarray): Array of f-test values for each regression.

glhmm.statistics.calculate_nan_correlation_matrix(D_data, R_data, pval_parametric=False)

Calculate the correlation matrix between independent variables (D_data) and dependent variables (R_data), while handling NaN values column by column of dimension p without without removing entire rows.

Parameters:

D_data (numpy.ndarray):

Input D-matrix for the independent variables.

R_data (numpy.ndarray):

Input R-matrix for the dependent variables.

pval_parametric (bool). Default is False:

Flag to mark if parametric p-values should calculated alongside the correlation cofficients or not.

Returns:

correlation_matrix (numpy.ndarray):

correlation matrix between columns in D_data and R_data.

glhmm.statistics.calculate_nan_t_test(Din, Rin, nan_values=False)

Calculate the t-statistics between paired independent (D_data) and dependent (R_data) variables, while handling NaN values column by column without removing entire rows.

• The function handles NaN values for each feature in D_data without removing entire rows.

• NaN values are omitted on a feature-wise basis, and the t-statistic is calculated for each feature.

• The resulting array contains t-statistics corresponding to each feature in D_data.

Parameters:

Din (numpy.ndarray):

The input matrix of shape (n_samples, n_features).

R_column (numpy.ndarray):

The binary labels corresponding to each sample in D_data.

Returns:

t_test (numpy.ndarray):

t-statistics for each feature in D_data against the binary categories in R_data.

glhmm.statistics.calculate_regression_f_stat_univariate(Din, Rin, idx_data, beta, perm, reg_pinv, permute_beta=False, test_indices=None)

Calculate F-statistics for each feature of Din against categories in R_data, while handling NaN values column by column without removing entire rows.

Parameters:

Din (numpy.ndarray):

Input data matrix for the independent variables.

Rin (numpy.ndarray):

Input data matrix for the dependent variables.

idx_data (numpy.ndarray):

An array containing the indices for each session. The array can be either 1D or 2D: For a 1D array, a sequence of integers where each integer labels the session number. For example, [1, 1, 1, 1, 2, 2, 2, …, N, N, N, N, N, N, N, N]. For a 2D array, each row represents the start and end indices for the trials in a given session, with the format [[start1, end1], [start2, end2], …, [startN, endN]].

beta (numpy.ndarray):

beta coefficient for each session. It has a shape (num_session, p, q), where the first dimension represents the session, the second dimension represents the featires, and the third dimension represent dependent variables.

perm (int):

The permutation index.

reg_pinv (numpy.ndarray):

The regularized pseudo-inverse of D_data

permute_beta (bool, optional):

A flag indicating whether to permute beta coefficients.

test_indices_list (numpy.ndarray), default=None:

Indices for data points that belongs to the test-set for each session.

Returns:

f_statistic (numpy.ndarray):

F-statistics for each feature in Din against the categories in R_data.

pval_matrix (numpy.ndarray):

parametric p-values estimated from the F-statistic

glhmm.statistics.calculate_regression_statistics(Din, Rin, reg_pinv, nan_values=False, no_t_stats=False)

Calculate the R-squared values for the regression of each dependent variable in Rin on the independent variables in Din, while handling NaN values column-wise.

Parameters:

Din (numpy.ndarray):

Input data matrix for the independent variables.

Rin (numpy.ndarray):

Input data matrix for the dependent variables.

reg_pinv (numpy.ndarray), default None:

The regularized pseudo-inverse of D_data

idx_data (numpy.ndarray):

Marks the indices for each trial within the session. It is a 2D array where each row represents the start and end index for a session.

permute_beta (bool, optional):

A flag indicating whether to permute beta coefficients.

beta (numpy.ndarray):

beta coefficient for each session. It has a shape (num_session, p, q), where the first dimension represents the session, the second dimension represents the featires, and the third dimension represent dependent variables.

test_indices (numpy.ndarray):

Indices for data points that belongs to the test-set for each session.

nan_values (bool, optional):

A flag indicating there are NaN values.

Returns:

R2_stats (numpy.ndarray): Array of R-squared values for each regression.

glhmm.statistics.calculate_statepair_difference(vpath_array, R_data, state_1, state_2, stat)

Calculate the difference between the specified statistics of two states.

Parameters:

vpath_data (numpy.ndarray):

The Viterbi path as of integer values that range from 1 to n_states.

R_data (numpy.ndarray):

The dependent-variable associated with each state.

state_1 (int):

First state for comparison.

state_2 (int):

Second state for comparison.

statistic (str):

The chosen statistic to be calculated. Valid options are “mean” or “median”.

Returns:

difference (float):

The calculated difference between the two states.

glhmm.statistics.categorize_columns_by_statistical_method(R_data, method, Nnull_samples, detect_categorical=False, category_limit=None, permute_beta=False, comparison_statistic=False)

Detects categorical columns in R_data and categorizes them for later statistical testing (t-tests, F-tests, etc.). This function helps identify which columns are binary or categorical, and applies permutation inference based on the test statistics.

Parameters:

R_datanumpy.ndarray

The 3D array (e.g., N x T x q) containing the data where categorical values need to be detected.

methodstr, optional

The statistical method applied to the columns. Supported values are: “univariate”, “multivariate”, “osr”, “osa”.

detect_categoricalbool, list, or numpy.ndarray, optional (default=False)

If True, automatically identify categorical columns. If a list or ndarray, the provided column indices are used for categorization.

category_limitint or None, optional (default=None)

The maximum allowed number of unique categories for an F-test. Used to prevent misidentifying continuous variables (like age) as categorical.

permute_betabool, optional (default=False)

Determines whether to use permutation testing on regression beta values.

comparison_statisticstr, optional (default=”mean”)

The statistic used in pairwise comparisons for methods like “osr” or “osa”. Supported values are “mean” or “median”.

Returns:

category_columnsdict

A dictionary with the following keys: - ‘t_stat_independent_cols’: Columns where t-tests are applied (binary variables). - ‘f_anova_cols’: Columns where F-tests (ANOVA) are applied (categorical variables). - ‘f_reg_cols’: Columns to apply F-regression on (continuous variables). - Other keys depending on method, such as ‘r_squared’, ‘corr_coef’, or ‘z_score’ for different tests.

glhmm.statistics.compute_cca_statistics(Din, Rin, test_statistics, perm, permute_beta=False, test_indices_con=None, idx_data=None, beta=None, n_cca_components=1)

Compute test statistics using Canonical Correlation Analysis (CCA).

Parameters:

Din (numpy.ndarray):

Input data matrix (predictors).

Rin (numpy.ndarray):

Target data matrix (responses).

test_statistics (numpy.ndarray):

Array storing computed statistics for permutations.

perm (int):

Permutation index.

permute_beta (bool, optional):

Whether to permute beta coefficients. Default is False.

test_indices_con (numpy.ndarray or None, optional):

Concatenated test indices for permutation. Default is None.

idx_data (numpy.ndarray or None, optional):

Indices for data selection. Default is None.

beta (numpy.ndarray or None, optional):

Beta coefficients for regression if permuting. Default is None.

n_cca_components (int, optional):

Number of CCA components to compute. Default is 1.

Returns:

base_statistics (numpy.ndarray):

Computed CCA correlation values for each component.

test_statistics (numpy.ndarray):

Updated test statistics

glhmm.statistics.compute_correlation_tstats(Din, Rin, pval_parametric=False)

Computes Pearson correlation coefficients and t-statistics between independent variables (Din) and dependent variables (Rin), with automatic NaN handling.

If no NaN values exist, it calls compute_correlation_and_tstats directly for fast vectorized computation. Otherwise, it processes each column pair individually while ignoring NaNs.

Parameters:

Din (numpy.ndarray):

Input D-matrix for the independent variables.

Rin (numpy.ndarray):

Input R-matrix for the dependent variables.

pval_parametric (bool, optional):

If True, calculates parametric p-values alongside the t-statistics. Default is False.

Returns:

correlation_matrix (numpy.ndarray):

Pearson correlation coefficients for each predictor-response pair.

t_statistics (numpy.ndarray):

t-statistics for each predictor-response pair.

pval_matrix (numpy.ndarray):

p-values for each predictor-response pair. If pval_parametric=False, this will be NaN.

glhmm.statistics.compute_max_permutations(block_indices=None, permute_within_blocks=False, permute_between_blocks=False, Nnull_samples=None, permute_beta=False, verbose=True)

Compute the maximum number of possible permutations based on the selected permutation strategy.

Parameters:

block_indices (numpy.ndarray), default=None:

A 1D array indicating block membership for each sample. Required when using block-based permutations.

permute_within_blocks (bool), default=False:

If True, subjects can permute within their respective blocks.

permute_between_blocks (bool), default=False:

If True, blocks of the same size can swap positions.

Nnull_samples (int), default=None:

The total number of independent samples for raw permutation. Required when permute_within_blocks=False and permute_between_blocks=False.

permute_beta (bool), default=False:

If True, permutations are performed at the beta level (e.g., shuffling session-level betas). Assumes one beta per unique block label.

verbose (bool), default=True:

If True, prints the total number of possible permutations and how many will be used.

Returns:

log_permutations (float):

The logarithm of the total number of possible permutations.

max_permutations (float):

The total number of possible permutations in exponential form (if computable without overflow).

Notes:

• If all permutation flags are False, the function assumes raw permutation across Nnull_samples.

• If permute_within_blocks is True, it computes the number of permutations possible within each block.

• If permute_between_blocks is True, it computes permutations between blocks of equal size.

• If both permute_within_blocks and permute_between_blocks are True, both effects are combined.

• If permute_beta is True, it treats each unique entry in block_indices as a permutable beta unit.

• Output formatting uses standard scientific notation (e.g., ‘1.30e+12’) and truncates mantissas instead of rounding.

glhmm.statistics.create_test_summary(Rin, base_statistics, pval, predictor_names, outcome_names, method, f_t_stats, n_T, n_N, n_p, n_q, Nnull_samples, category_columns=None, combine_tests=False, test_indices_list=None)

Create a summary report for the test.

Parameters:

Rin (numpy.ndarray):

Input data matrix for the dependent variables (shape: n_samples x n_outcomes).

base_statistics (numpy.ndarray):

Array of R² or correlation coefficients, depending on the method used.

pval (numpy.ndarray):

Array of p-values corresponding to the base statistics.

predictor_names (list of str):

List of names for the predictors.

outcome_names (list of str):

List of names for the outcomes.

method (str):

Specifies the method used for testing. Options are: - “multivariate”: For regression analysis with multiple predictors and outcomes. - Other: For other tests

F_stats_list (numpy.ndarray):

Array of F-statistics across permutations (shape: n_T x Nnull_samples x n_q for time-dependent data, or Nnull_samples x n_q for time-independent data).

t_stats_list (numpy.ndarray):

Array of t-statistics across permutations (shape: n_T x Nnull_samples x n_p x n_q for time-dependent data, or Nnull_samples x n_p x n_q for time-independent data).

n_T (int):

Number of timepoints (set to 1 for time-independent data).

n_N (int):

Number of observations.

n_p (int):

Number of predictors.

n_q (int):

Number of outcomes.

Returns:

test_summary (dict):

A dictionary containing the summary report of the test

glhmm.statistics.deconfound_values(D_data, R_data, confounds=None)

Deconfound the variables R_data and D_data for permutation testing.

Parameters:

D_data (numpy.ndarray):

The input data array.

R_data (numpy.ndarray or None):

The second input data array, default= None. If None, assumes we are working across visits, and R_data represents the Viterbi path of a sequence.

confounds (numpy.ndarray or None):

The confounds array, default= None.

Returns:

D_t (numpy.ndarray):

D_data with confounds regressed out.

R_t (numpy.ndarray):

R_data with confounds regressed out.

glhmm.statistics.define_predictor_outcome_names(method, combine_tests, predictor_names, outcome_names, n_p, n_q)

Define predictor and outcome names based on the selected statistical method and test combination settings.

Parameters:

method (str):

The statistical method used for analysis. Valid options: - ‘multivariate’: Uses multiple predictors together to find patterns. - ‘univariate’: Tests each predictor separately. - ‘cca’: Canonical Correlation Analysis, finding a single pattern across two data sets.

combine_test (bool or str):

Determines how test results are combined: - True: Produces a single p-value for the entire test (1 × 1). - “across_rows”: Produces one p-value per outcome (1 × q). - “across_columns”: Produces one p-value per predictor (1 × p). - False: No test combination, default.

predictor_names (list of str):

Names of predictor variables. If empty or mismatched with n_p, default names are assigned.

outcome_names (list of str):

Names of outcome variables. If empty or mismatched with n_q, default names are assigned.

n_p (int):

Number of predictor variables.

n_q (int):

Number of outcome variables.

Returns:

predictor_name (str or list):

Assigned name(s) for the predictor variable(s).

outcome_name (str or list):

Assigned name(s) for the outcome variable(s).

glhmm.statistics.detect_significant_intervals(pval, alpha)

Detect intervals of consecutive True values in a boolean array.

Parameters:

p_values (numpy.ndarray):

An array of p-values.

alpha (float, optional):

Threshold for significance.

Returns:

intervals (list of tuple):

A list of tuples representing the start and end indices (inclusive) of each interval of consecutive True values.

Example:

array = [False, False, False, True, True, True, False, False, True, True, False] detect_intervals(array) output: [(3, 5), (8, 9)]

glhmm.statistics.display_test_summary(result_dict, output='both', timepoint=0, return_tables=False)

Display or export test summary from result_dict.

Parameters:

result_dict (dict):

A dictionary including: - ‘base_statistics’: Array of base statistics (e.g., correlation coefficients). - ‘pval’: Array of p-values from permutation testing. - ‘test_summary’: A dictionary containing the summary report of the test

output (str, optional):

Specifies the output to display. Options are: - “both”: Display both Model Summary and Coefficients Table (default). - “model”: Display only the Model Summary. - “coef”: Display only the Coefficients Table.

timepoint (int, optional):

Specifies the timepoint index if T-statistics are time-dependent.

return_tables (bool, optional):

If True, returns the Model Summary and/or Coefficients Table as pandas DataFrames. If False, simply displays the tables (default).

Returns:

None if return_tables is False. If return_tables is True:

• Returns a tuple (model_summary, coef_table) if output=”both”.

• Returns model_summary if output=”model”.

• Returns coef_table if output=”coef”.

glhmm.statistics.ensure_list(value)

Ensure the input is returned as a list.

This function converts scalar values and strings into a list while leaving iterable inputs unchanged.

Parameters:

value (any):

The input value, which can be a scalar, string, or an iterable.

Returns:

list:

• If value is a scalar (numeric or boolean) or a string, it is wrapped in a list.

• If value is already an iterable (e.g., list, tuple, numpy array), it is returned unchanged.

glhmm.statistics.expand_variable_permute_beta(base_statistics, test_statistics_list, idx_array, method)

Expand the base statistics and test statistics for permutation testing.

Parameters:

base_statistics (numpy.ndarray):

The base statistics array.

test_statistics_list (numpy.ndarray):

The list of test statistics arrays.

idx_array (numpy.ndarray):

The array containing indices.

method (str):

The method used for expansion. Options: “multivariate”, other.

Returns:

base_statistics (numpy.ndarray):

The expanded base statistics array.

test_statistics_list (numpy.ndarray):

The expanded list of test statistics arrays.

glhmm.statistics.generate_vpath_1D(vpath)

Convert a 2D array representing a matrix with one non-zero element in each row into a 1D array where each element is the column index of the non-zero element.

Parameters:

vpath(numpy.ndarray):

A 2D array where each row has only one non-zero element. Or a 1D array where each row represents a sate number

Returns:

vpath_array(numpy.ndarray):

A 1D array containing the column indices of the non-zero elements. If the input array is already 1D, it returns a copy of the input array.

glhmm.statistics.geometric_pvalue(p_values, combine_tests)

Calculate the geometric combination of p-values.

Parameters:

p_values (numpy.ndarray):

A 2D array representing the parametric p-values between variables.

combine_tests (bool or str):

Specifies the method for combining the p-values: - True: Compute the geometric mean of all p-values (1-by-1). - “across_columns”: Compute the geometric mean for each column, returning an array of shape (1-by-q). - “across_rows”: Compute the geometric mean for each row, returning an array of shape (1-by-p).

Returns:

corr_combination (numpy.ndarray):

The combined p-values based on the specified combine_tests method.

glhmm.statistics.get_concatenate_data_memmap(D_raw, filename='D_con.dat')

Saves a list of NumPy arrays (D_raw) into a memory-mapped file to optimize RAM usage.

Parameters:

D_rawlist of np.ndarray

List containing session-wise NumPy arrays with the same number of columns.

filenamestr, optional

Name of the memory-mapped file to store the concatenated dataset (default is “D_con.dat”).

Returns:

np.memmap

Memory-mapped NumPy array containing the concatenated data.

glhmm.statistics.get_concatenate_sessions(D_sessions, R_sessions=None, idx_sessions=None)

Converts a 3D matrix into a 2D matrix by concatenating timepoints of every trial session into a new D-matrix.

Parameters:

D_sessions (numpy.ndarray):

D-matrix for each session.

R_sessions (numpy.ndarray):

R-matrix time for each trial.

idx_sessions (numpy.ndarray):

Indices representing the start and end of trials for each session.

Returns:

D_con (numpy.ndarray):

Concatenated D-matrix.

R_con (numpy.ndarray):

Concatenated R-matrix.

idx_sessions_con (numpy.ndarray):

Updated indices after concatenation.

glhmm.statistics.get_concatenate_subjects(D_sessions)

Converts a 3D matrix into a 2D matrix by concatenating timepoints of every subject into a new D-matrix.

Parameters:

D_sessions (numpy.ndarray):

D-matrix for each subject.

Returns:

D_con (numpy.ndarray):

Concatenated D-matrix.

glhmm.statistics.get_event_epochs(input_data, index_data, filtered_R_data, event_markers, fs, fs_target=None, ms_before_stimulus=0, epoch_window_tp=None)

Extract time-locked data epochs based on stimulus events.

This function processes 2D input data to extract epochs aligned to specific stimulus events. The epochs are extracted based on provided event files and are resampled to the target rate. The function also returns relevant indices and concatenates filtered R data across sessions.

Parameters:

input_data (numpy.ndarray):

2D array containing gamma values for the session, structured as ((number of timepoints * number of trials), number of states).

index_data (numpy.ndarray):

2D array containing preprocessed indices for the session.

filtered_R_data (list):

List of filtered R data arrays for each session based on the events.

event_markers (list):

List of event information for each session.

fs (int, optional):

The original sampling frequency in Hz. Defaults to 1000 Hz.

fs_target (int, optional):

The target sampling frequency in Hz after resampling. Defaults to 250 Hz.

ms_pre_stimulus (int, optional):

Time in milliseconds to offset the start of the epoch before the stimulus onset. Defaults to 0 ms.

epoch_window_tp

Epoch window length in time points. If None, a default duration of 1 second (equal to fs_target) is used.

Returns:

epoch_data (numpy.ndarray):

3D array of extracted data epochs, structured as (number of timepoints, number of trials, number of states).

epoch_indices (numpy.ndarray):

Array of indices corresponding to the extracted epochs for each session.

concatenated_R_data (numpy.ndarray):

Concatenated array of R data across all sessions.

glhmm.statistics.get_f_t_stats(D_data, R_data, F_stats_list, t_stats_list, Nnull_samples, n_T)

Compute F and t statistics along with permutation-based p-values and confidence intervals.

This function calculates F and t statistics from input data and, if permutations are used, estimates p-values and confidence intervals by comparing observed statistics to permuted values.

Parameters:

D_data (numpy.ndarray):

Predictor data of shape (n, p), where: - n is the number of samples (e.g., trials, subjects). - p is the number of predictor variables.

R_data (numpy.ndarray):

Outcome data of shape (n, q), where: - n is the number of samples. - q is the number of outcome variables.

F_stats_list (numpy.ndarray):

Array of F-statistics across permutations, with shape (n_T, Nnull_samples + 1, q). The first index ([:, 0, :]) contains observed statistics, while remaining indices contain permuted values.

t_stats_list (numpy.ndarray):

Array of t-statistics across permutations, with shape (n_T, Nnull_samples + 1, p, q). The first index ([:, 0, :, :]) contains observed statistics, while remaining indices contain permuted values.

Nnull_samples (int):

Number of permutations used in the test.

n_T (int):

Number of timepoints or conditions.

Returns:

f_t_stats (dict):

A dictionary containing the computed statistics: - ‘perm_p_values_F’ (numpy.ndarray): Permutation-based p-values for F-statistics,

with shape (n_T, q).

• ‘perm_p_values_t’ (numpy.ndarray): Permutation-based p-values for t-statistics, with shape (n_T, p, q).

• ‘perm_ci_lower’ (numpy.ndarray): Lower bound of the 95% confidence interval for t-statistics, with shape (n_T, p, q).

• ‘perm_ci_upper’ (numpy.ndarray): Upper bound of the 95% confidence interval for t-statistics, with shape (n_T, p, q).

• ‘F_stats’ (numpy.ndarray): Observed F-statistics, with shape (n_T, q).

• ‘t_stats’ (numpy.ndarray): Observed t-statistics, with shape (n_T, p, q).

glhmm.statistics.get_indices_array(idx_data)

Generates an indices array based on given data indices.

Parameters:

idx_data (numpy.ndarray):

The data indices array.

Returns:

idx_array (numpy.ndarray):

The generated indices array.

Example:

>>> idx_data = np.array([[0, 3], [3, 6], [6, 9]])
>>> get_indices_array(idx_data)
array([0, 0, 0, 1, 1, 1, 2, 2, 2])

glhmm.statistics.get_indices_from_list(data_list, count_timestamps=True)

Generate indices representing the start and end timestamps for each subject or session from a given data list.

Parameters:

data_list (list):

List containing data for each subject or session.

count_timestamps (bool), default=True:

If True, counts timestamps for each element in data_list, otherwise assumes each element in data_list is already a count of timestamps.

Returns:

indices (ndarray):

Array with start and end indices for each subject’s timestamps.

Example:

>>> data_list = [[1, 2, 3], [4, 5], [6]]
>>> get_indices_from_list(data_list, count_timestamps=True)
array([[0, 3],
       [3, 5],
       [5, 6]])

>>> data_list = [3, 2, 1]
>>> get_indices_from_list(data_list, count_timestamps=False)
array([[0, 3],
       [3, 5],
       [5, 6]])

glhmm.statistics.get_indices_range(size, step)

Create a 2D matrix of start and end indices with a fixed step size.

Parameters:

size (int):

The total size of the data to generate indices for.

step (int):

The step size for each range.

Returns:

indices (ndarray):

A 2D NumPy array where each row represents the start and end indices.

Example:

>>> size = 1000
>>> step = 250
>>> get_indices_range(size, step)
array([[   0,  250],
       [ 250,  500],
       [ 500,  750],
       [ 750, 1000]])

glhmm.statistics.get_indices_session(data_label)

Generate session indices in the data based on provided labels. This is done by using ‘data_label’ to define sessions and generates corresponding indices. The resulting ‘idx_data_sessions’ array represents the intervals for each session in the data.

Parameters:

data_label (ndarray):

Array representing the labels for data to be indexed into sessions.

Returns:

idx_data_sessions (ndarray):

The indices of datapoints within each session. It should be a 2D array where each row represents the start and end index for a trial.

Example:

>>> data_label = np.array([0, 0, 0, 1, 1, 2])
>>> get_indices_session(data_label)
array([[0, 3],
       [3, 5],
       [5, 6]])

glhmm.statistics.get_indices_timestamp(n_timestamps, n_subjects)

Generate indices of the timestamps for each subject in the data.

Parameters:

n_timestamps (int):

Number of timestamps.

n_subjects (int):

Number of subjects.

Returns:

indices (ndarray):

Array representing the indices of the timestamps for each subject.

Example:

>>> n_timestamps = 3
>>> n_subjects = 4
>>> get_indices_timestamp(n_timestamps, n_subjects)
array([[ 0,  3],
       [ 3,  6],
       [ 6,  9],
       [ 9, 12]])

glhmm.statistics.get_indices_update_nan(idx_data, nan_mask)

Update interval indices based on missing values in the data.

Parameters:

idx_data (numpy.ndarray):

Array of shape (n_intervals, 2) representing the start and end indices of each interval.

nan_mask (bool):

Boolean mask indicating the presence of missing values in the data.

Returns:

idx_data_update (numpy.ndarray):

Updated interval indices after accounting for missing values.

glhmm.statistics.get_input_shape(D_data, R_data, verbose)

Computes the input shape parameters for permutation testing.

Parameters:

D_data (numpy.ndarray):

The input data array.

R_data (numpy.ndarray):

The dependent variable.

verbose (bool):

If True, display progress messages. If False, suppress progress messages.

Returns:

n_T (int):

The number of timepoints.

n_ST (int):

The number of subjects or trials.

n_p (int):

The number of features.

D_data (numpy.ndarray):

The updated input data array.

R_data (numpy.ndarray):

The updated dependent variable.

glhmm.statistics.get_pval(test_statistics, Nnull_samples, method, t, pval, FWER_correction=False)

Computes p-values from the test statistics. # Ref: https://github.com/OHBA-analysis/HMM-MAR/blob/master/utils/testing/permtest_aux.m

Parameters:

test_statistics (numpy.ndarray):

The permutation array.

pval_perms (numpy.ndarray):

The p-value permutation array.

Nnull_samples (int):

The number of permutations.

method (str):

The method used for permutation testing.

t (int):

The timepoint index.

pval (numpy.ndarray):

The p-value array.

Returns:

pval (numpy.ndarray):

Updated updated p-value .

glhmm.statistics.handle_nan_values(D_data, R_data, permutation_matrix, method)

Check for NaN values at the first time point and update data and the permutation matrix if needed.

Parameters:

D_datanumpy.ndarray

Array of shape (n_T, n_samples, n_features) representing the dependent variable data.

R_datanumpy.ndarray

Array of shape (n_samples, n_regressors) representing the independent variable data.

permutation_matrixnumpy.ndarray

Permutation matrix used for statistical testing.

methodstr

Statistical method being used. NaN handling is applied only if method is “multivariate” or “cca”.

Returns:

D_datanumpy.ndarray

Updated dependent variable data with NaNs removed if necessary.

R_datanumpy.ndarray

Updated independent variable data with NaNs removed if necessary.

permutation_matrix_updatenumpy.ndarray

Updated permutation matrix if NaNs were found; otherwise, a copy of the original.

FLAG_NANbool

Indicates whether NaN handling is required in future iterations.

glhmm.statistics.initialize_arrays(n_p, n_q, n_T, method, Nnull_samples, return_base_statistics, combine_tests=False, n_cca_components=None)

Initializes arrays for permutation testing based on the selected method and test parameters.

Parameters:

n_p (int):

Number of features.

n_q (int):

Number of predictions.

n_T (int):

Number of timepoints.

method (str):

Statistical testing method. Valid options: “multivariate”, “cca”, “univariate”, “osa”, “osr”.

Nnull_samples (int):

Number of permutations.

return_base_statistics (bool):

If True, returns test statistics values.

combine_tests (str or bool, optional):

Specifies how tests are combined. Valid options: - True: Combine across all dimensions. - “across_columns”: Combine across features (n_p). - “across_rows”: Combine across predictions (n_q). - Default is False (no combination).

Returns:

pval (numpy.ndarray):

p-values for the test. Shape varies based on method and combine_tests: - (n_T, 1) if combine_tests=True - (n_T, n_p) if combine_tests=”across_columns” - (n_T, n_q) if combine_tests=”across_rows” - (n_T, n_p, n_q) for univariate tests without combination - (n_T, 1) for CCA - (n_T, n_q) for multivariate - (n_T, n_p, n_p, n_q) for OSA - (n_T, 1, n_p, n_q) for OSR

base_statistics (numpy.ndarray):

Base statistics of a given test, with the same shape as pval.

test_statistics_list (numpy.ndarray or None):

Test statistic values, only returned if return_base_statistics=True. - Shape (n_T, Nnull_samples, 1), (n_T, Nnull_samples, n_p), or (n_T, Nnull_samples, n_q) based on combine_tests for univariate tests. - Shape (n_T, Nnull_samples, n_q) for multivariate tests. - Shape (n_T, Nnull_samples, 1) for CCA. - Shape (n_T, Nnull_samples, len(pairwise_comparisons), n_q) for OSA. - Shape (n_T, Nnull_samples, n_p, n_q) for OSR. - None if return_base_statistics=False.

F_stats_list (numpy.ndarray):

F-statistics for permutation tests. Shape: (n_T, Nnull_samples, n_q).

t_stats_list (numpy.ndarray):

t-statistics for permutation tests. Shape: (n_T, Nnull_samples, n_p, n_q).

R2_stats_list (numpy.ndarray or None):

R² statistics for permutation tests, only available for “multivariate” tests. Shape: (n_T, Nnull_samples, n_q) if method=”multivariate”, otherwise None.

glhmm.statistics.initialize_permutation_matrices(method, Nnull_samples, n_p, n_q, D_data, combine_tests=False, permute_beta=False, category_columns=None, n_cca_components=1)

Initializes the permutation matrices and prepare the regularized pseudo-inverse of D_data.

Parameters:

method (str):

The method to use for permutation testing.

Nnull_samples (int):

The number of permutations.

n_p (int):

The number of features.

n_q (int):

The number of predictions.

D_data (numpy.ndarray):

The independent variable.

combine_tests (str), default=False:

Specifies the combination method. Valid options: “True”, “across_columns”, “across_rows”.

permute_beta (bool, optional), default=False:

A flag indicating whether to permute beta coefficients.

Returns:

test_statistics (numpy.ndarray):

The permutation array.

pval_perms (numpy.ndarray):

The p-value permutation array.

reg_pinv (numpy.ndarray or None):

The regularized pseudo-inverse of D_data.

glhmm.statistics.inverse_fisher_z(z_matrix)

Convert z-scores back to correlation coefficients using the inverse Fisher z-transformation.

Parameters: z_matrix (ndarray):

A matrix of z-scores.

Returns: ndarray:

A matrix of correlation coefficients.

glhmm.statistics.ols_regression_sessions(Rin, Din, idx_data, beta, perm, permute_beta=False, nan_values=False, valid_indices=None, regression_statistics=False, Nnull_samples=False, no_t_stats=False, method=None)

Calculate predictions for ordinary least squares regression for across sessions test.

Parameters:

reg_pinv (numpy.ndarray):

The regularized pseudo-inverse of D_data.

D_data (numpy.ndarray):

The input data array.

R_data (numpy.ndarray):

The dependent variable. Design matrix.

idx_data (numpy.ndarray):

Marks the indices for each trial within the session. It is a 2D array where each row represents the start and end index for a session.

perm (int):

Value marking the number of permutations that have been performed.

permute_beta (bool, optional):

Whether to permute beta. Default is False.

nan_values (bool, optional):

Whether to handle NaN values. Default is False.

valid_indices (numpy.ndarray, optional):

Valid indices. Default is None.

regression_statistics (bool, optional):

Flag indicating whether to compute regression statistics (R-squared, F-statistics, and t-statistics). Default is False.

Returns:

R_pred (numpy.ndarray):

Predicted values from the OLS regression when regression_statistics is False.

R2_stats (numpy.ndarray), F_stats (numpy.ndarray), t_stats (numpy.ndarray):

If regression_statistics is True, returns R-squared, F-statistics, and t-statistics for each session.

glhmm.statistics.ols_regression_stats(Din, Rin, R_pred, Nnull_samples, no_t_stats, valid_indices=None)

Compute regression statistics (R-squared, F-statistics, and t-statistics) for ordinary least squares (OLS) regression across multiple sessions.

Parameters:

Din (numpy.ndarray):

The design matrix (D-matrix) containing independent variables. Shape: (n, p), where n is the number of observations and p is the number of predictors.

Rin (numpy.ndarray):

The dependent variable matrix (R-matrix) containing observed values. Shape: (n, q), where q is the number of dependent variables.

R_pred (numpy.ndarray):

The predicted response matrix. Shape: (n, q).

Nnull_samples (numpy.ndarray):

Number of permutations

Returns:

R2_stats (numpy.ndarray):

R-squared values for each dependent variable. Shape: (q,).

F_stats (numpy.ndarray):

F-statistics for each dependent variable. Shape: (q,).

t_stats (numpy.ndarray):

The calculated t-statistics for each predictor-outcome pair. Shape: (p, q).

Notes:

This approach is based on the statistical relationship between Pearson correlation coefficients and t-distributions. By relying on R_pred rather than beta coefficients, the permutation process directly influences the t-statistics.

glhmm.statistics.pad_vpath(vpath, lag_val, indices_tde=None)

Pad the Viterbi path with repeated first and last rows.

This function adds padding to the beginning and end of a given Viterbi path (vpath) from a Hidden Markov Model by repeating the first and last rows a specified number of times (lag_val). This is useful for maintaining boundary conditions in scenarios such as sequence alignment or signal processing where the state transitions need to be preserved.

Parameters:

vpath (numpy.ndarray):

A 2D array representing the Viterbi path, where each row corresponds to a specific state in the HMM and each column represents different features or observations.

lag_val (int):

The number of times to repeat the first and last rows for padding.

indices_tde (list of tuples, optional):

A list of tuples, where each tuple contains the start and end indices of individual sequences within the vpath. If provided, padding is applied to each sequence separately.

indices_tde (numpy.ndarray):

Is a 2D array where each row represents the start and end index for a session for the TDE-HMM dataset.

Returns:

numpy.ndarray:

A new 2D array containing the padded Viterbi path, with shape ((lag_val + n_rows + lag_val), n_features), where n_rows is the original number of rows in vpath and n_features is the number of features.

Raises:

ValueError:

If lag_val is not a positive integer, or if vpath is not a 2D numpy array.

glhmm.statistics.permutation_matrix_across_subjects(Nnull_samples, R_data)

Generates a normal permutation matrix with the assumption that each index is independent across subjects.

Parameters:

Nnull_samples (int):

The number of permutations.

R_data (numpy.ndarray):

R-matrix at timepoint ‘t’

Returns:

permutation_matrix (numpy.ndarray):

Permutation matrix of subjects it got a shape (n_ST, Nnull_samples)

glhmm.statistics.permutation_matrix_across_trials_within_session(Nnull_samples, R_data, idx_array, trial_timepoints=None)

Generates permutation matrix of within-session across-trial data based on given indices.

Parameters:

Nnull_samples (int):

The number of permutations.

R_data (numpy.ndarray):

The preprocessed data array.

idx_array (numpy.ndarray):

The indices array.

trial_timepoints (int):

Number of timepoints for each trial, default = None

Returns:

permutation_matrix (numpy.ndarray):

Permutation matrix of subjects it got a shape (n_ST, Nnull_samples)

glhmm.statistics.permutation_matrix_within_and_between_groups(Nnull_samples, R_data, idx_array)

Generates a permutation matrix with permutations within and between groups.

Parameters:

Nnull_samples (int):

The number of permutations.

R_data (numpy.ndarray):

The R_data array used for generating the within-group permutation matrix.

idx_array (numpy.ndarray):

The indices array that groups the R_data (e.g., session or subject identifiers).

Returns:

permutation_matrix (numpy.ndarray):

The matrix with both within- and between-group permutations.

glhmm.statistics.permutation_matrix_within_subject_across_sessions(Nnull_samples, R_data, idx_array)

Generates permutation matrix of within-session across-session data based on given indices.

Parameters:

Nnull_samples (int):

The number of permutations.

R_data (numpy.ndarray):

The preprocessed data array.

idx_array (numpy.ndarray):

The indices array.

Returns:

permutation_matrix (numpy.ndarray):

The within-session continuos indices array.

glhmm.statistics.permute_subject_trial_idx(idx_array, unique_values=None, value_counts=None)

Permutes an array based on unique values while maintaining the structure.

Parameters:

idx_array (numpy.ndarray):

Input array to be permuted.

Returns:

permuted_array (numpy.ndarray):

Permuted matrix based on unique values.

glhmm.statistics.preprocess_response(Rin)

Converting R_in into to dummy variables, and centering the data around zero.

Parameters:

Rin (numpy.ndarray or pandas.Series):

Input array representing the dependent variable. Can be 1D or 2D. If 1D, it will be flattened and converted to dummy variables.

Returns:

Rin_centered (numpy.ndarray):

A 2D array of centered dummy variables based on the input response.

glhmm.statistics.process_family_structure(dict_family, Nnull_samples)

Process a dictionary containing family structure information.

Parameters:

dict_family (dict): Dictionary containing family structure information.

file_location (str): The file location of the family structure data in CSV format. M (numpy.ndarray, optional): The matrix of attributes, which is not typically required.

Defaults to None.

nP (int): The number of permutations to generate. CMC (bool, optional): A flag indicating whether to use the Conditional Monte Carlo method (CMC).

Defaults to False.

EE (bool, optional): A flag indicating whether to assume exchangeable errors, which allows permutation.

Defaults to True.

Nnull_samples (int): Number of permutations.

Returns:

dict_mfam (dict): Modified dictionary with processed values.

EB (numpy.ndarray):

Block structure representing relationships between subjects.

M (numpy.ndarray, optional), default=None:

The matrix of attributes, which is not typically required.

nP (int):

The number of permutations to generate.

CMC (bool, optional), default=False:

A flag indicating whether to use the Conditional Monte Carlo method (CMC).

EE (bool, optional), default=True:

A flag indicating whether to assume exchangeable errors, which allows permutation.

glhmm.statistics.pval_FWER_correction(result_dic=None, test_statistics=None, Nnull_samples=None, method=None)

Compute Family-Wise Error Rate (FWER) corrected p-values for multivariate or univariate methods.

Parameters:

result_dic (dict, default None:

A dictionary containing “null_stat_distribution”, “Nnull_samples”, and “method”.

test_statistics (numpy.ndarray), default None:

The permutation array, where the first row/element contains observed statistics.

Nnull_samples (int), default None:

The number of permutations.

method (str), default None:

The method used for permutation testing. Can be “multivariate” or “univariate”.

Returns:

pval_FWER (numpy.ndarray):

FWER-corrected p-values.

glhmm.statistics.pval_cluster_based_correction(result_dic=None, test_statistics=[], pval=None, alpha=0.05, individual_feature=False)

Perform cluster-based correction on test statistics using the output from permutation testing. The function corrects p-values by using the test statistics and p-values obtained from permutation testing. It converts the test statistics into z-scores, thresholds them to identify clusters, and uses the cluster sizes to adjust the p-values.

Parameters:

test_statistics (numpy.ndarray):

3D or 4D array of test statistics. For a 3D array, it should have a shape of (timepoints, permutations, p). For a 4D array, it should have a shape of (timepoints, permutations, p, q), where p represents the number of predictors/features. The first dimension corresponds to timepoints, the second dimension to different permutations, and the third (if present) to multiple features.

pval (numpy.ndarray):

1D or 2D array of p-values obtained from permutation testing. For a 1D array, it should have a shape of (timepoints), containing a single p-value per timepoint. For a 2D array, it should have a shape of (timepoints, p), where p represents the number of predictors/features.

alpha (float, optional), default=0.05:

Significance level for cluster-based correction.

individual_feature (bool, optional), default=False:

If True, the cluster-based correction is performed separately for each feature in the test_statistics. If False, the correction is applied to the entire p-value matrix.

Returns:

p_values (numpy.ndarray):

Corrected p-values after cluster-based correction.

glhmm.statistics.pval_correction(result_dic=None, pval=None, method='fdr_bh', alpha=0.05, include_nan=True, nan_diagonal=False)

Adjusts p-values for multiple testing.

Parameters:

pval (numpy.ndarray):

numpy array of p-values.

method (str, optional): method used for FDR correction, default=’fdr_bh.

bonferroni : one-step correction sidak : one-step correction holm-sidak : step down method using Sidak adjustments holm : step-down method using Bonferroni adjustments simes-hochberg : step-up method (independent) hommel : closed method based on Simes tests (non-negative) fdr_bh : Benjamini/Hochberg (non-negative) fdr_by : Benjamini/Yekutieli (negative) fdr_tsbh : two stage fdr correction (non-negative) fdr_tsbky : two stage fdr correction (non-negative)

alpha (float, optional):

Significance level, default= 0.05.

include_nan, default=True:

Include NaN values during the correction of p-values if True. Exclude NaN values if False.

nan_diagonal, default=False:

Add NaN values to the diagonal if True.

Returns:

pval_corrected (numpy.ndarray):

numpy array of corrected p-values. - 2D: (p, q), where p is the number of predictors and q is the number of outcome variables. - 3D: (T, p, q), where p is te number of timepoints, p is the number of predictors and q is the number of outcome variables.

significant (numpy.ndarray):

numpy array of boolean values indicating significant p-values.

glhmm.statistics.reconstruct_concatenated_to_3D(D_con, D_original=None, n_timepoints=None, n_entities=None, n_features=None)

Reshape a concatenated 2D matrix back into its original 3D format (timepoints, trials, channels).

This function converts a concatenated 2D matrix D_con (e.g., from HMM Gamma values) back into its original 3D shape. If the original session matrix D_original is provided, the function will infer the number of timepoints, trials, and channels from its shape. Otherwise, the user must provide the correct dimensions.

Parameters:

D_con (numpy.ndarray):

A 2D concatenated D-matrix of shape ((n_timepoints * n_entities), n_features).

D_original (numpy.ndarray, optional):

A 3D array containing the original D-matrices for each session, with shape (n_timepoints, n_entities, n_features).

n_timepoints (int, optional):

A number of timepoints per trial, is required if D_original is not provided.

n_entities (int, optional):

A number of e.g. trials or subjects per session, is required if D_original is not provided.

n_features (int, optional):

Number of features (e.g. channels), required if D_original is not provided.

Returns:

D_reconstruct (numpy.ndarray):

A 3D array containing the reconstructed D-matrix for each session, with shape (n_timepoints, n_entities, n_features).

Raises:

ValueError:

If D_original is provided and is not a 3D numpy array, or if the provided dimensions do not match the shape of D_con. If n_timepoints, n_trials, or n_features are not provided when D_original is missing. If the shape of D_con does not match the expected dimensions based on the input parameters.

glhmm.statistics.remove_nan_values(D_data, R_data, method)

Remove rows with NaN values from input data arrays.

Parameters:

D_data (numpy.ndarray)

Input data array containing features.

R_data (numpy.ndarray):

Input data array containing response values.

method (str, optional), default=”multivariate”:

Statistical method for the permutation test. Valid options are “multivariate”, “univariate”, “cca”, “osr” or “osa”. Note: “cca” stands for Canonical Correlation Analysis.

Returns:

D_data (numpy.ndarray):

Cleaned feature data (D_data) with NaN values removed.

R_data (numpy.ndarray):

Cleaned response data (R_data) with NaN values removed.

nan_mask(bool)

Array that mask the position of the NaN values with True and False for non-nan values

glhmm.statistics.squeeze_first_dim(array)

Conditionally squeeze a 3D numpy array if its first dimension has size 1.

Parameters:

array (numpy.ndarray or None):

A numpy array that may be 3-dimensional. Can also be None.

Returns:

numpy.ndarray or None:

• If the input array is 3D and its first dimension has size 1, the array is squeezed along the first dimension and the result is returned.

• If the input array is not 3D, or its first dimension is not of size 1, the array is returned as is.

• If the input is None, None is returned.

glhmm.statistics.surrogate_state_time(perm, viterbi_path, n_states)

Generates surrogate state-time matrix based on a given Viterbi path.

Parameters:

perm (int):

The permutation number.

viterbi_path (numpy.ndarray):

1D array or 2D matrix containing the Viterbi path.

n_states (int):

The number of states

Returns:

viterbi_path_surrogate (numpy.ndarray):

A 1D array representing the surrogate Viterbi path

glhmm.statistics.surrogate_state_time_matrix(Nnull_samples, vpath_data, n_states)

Generate a matrix of surrogate Viterbi paths by permuting state assignments while ensuring that all states are represented in each permutation.

Parameters:

Nnull_samples (int):

The number of surrogate permutations to generate.

vpath_data (numpy.ndarray):

The original Viterbi path data, representing the state sequence.

n_states (int):

The total number of states.

Returns:

vpath_surrogates (numpy.ndarray):

A 2D array of shape (len(vpath_data), Nnull_samples), where each column is a surrogate Viterbi path that maintains the segment structure and ensures all states are included.

glhmm.statistics.surrogate_viterbi_path(viterbi_path, n_states)

Generate a surrogate Viterbi path while keeping the segment structure intact. Each segment (continuous run of the same state) is reassigned to a new state, ensuring that no two consecutive segments

Parameters:

viterbi_path (numpy.ndarray):

1D array representing the original Viterbi path with unique state segments.

n_states (int):

The total number of states.

Returns:

viterbi_path_surrogate (numpy.ndarray):

A 1D array with the same segmentation pattern but reassigned states, ensuring that no segment is mapped to the same state as the previous one.

glhmm.statistics.test_across_sessions_within_subject(D_data, R_data, idx_data, method='multivariate', Nnull_samples=0, confounds=None, FWER_correction=False, combine_tests=False, detect_categorical=False, category_limit=10, n_cca_components=1, predictor_names=[], outcome_names=[], return_base_statistics=True, verbose=True)

Perform permutation testing across sessions while maintaining trial order.

This test assesses whether session-to-session variations in predictor data (D_data) correspond to differences in outcome data (R_data). For example, it can evaluate whether neural responses (D_data) change across repeated sessions of the same task (R_data), such as tracking performance improvements or shifts in brain activity over time.

Parameters:

D_data (numpy.ndarray):

Predictor data representing brain activity or other features. - 2D: (n, p), where n is the number of trials and p is the number of predictors. - 3D: (T, n, p), where T is the number of timepoints, n is the number of trials, and p is the number of predictors.

R_data (numpy.ndarray):

Outcome data representing behavioral responses or other dependent measures. - 2D: (n, q), where n is the number of trials and q is the number of outcome variables.

idx_data (numpy.ndarray):

Defines how trials are grouped into different sessions (e.g., trial type labels or session indices). - 1D array: Specifies group labels for each subject or session (e.g., [1,1,1,2,2,2,…,N]). - 2D array: Defines trial boundaries for each session as a list of [start, end] index pairs (e.g., [[0, 50], [50, 100], [100, 150], …, [N_start, N_end]]).

method (str, optional), default=”multivariate”:

The statistical method used to compare differences across sessions. Valid options are: - “multivariate”: Examines whether multiple predictors (e.g., brain states) changes across sessions. - “univariate”: Tests each predictor individually to assess whether it varies across sessions (e.g., whether specific brain states when doing the same task changes across session). - ‘cca’: Stands for Canonical Correlation Analysis; Identifies patterns of shared variation between predictors and outcomes across sessions, returning a single p-value indicating whether they are linked overall.

Nnull_samples (int), default=0:

Number of samples used to generate the null distribution, obtained via permutation. Set Nnull_samples=0 for parametric test output.

FWER_correction (bool, optional), default=False:

If True, applies family-wise error rate (FWER) correction using the MaxT method to reduce false positives.

confounds (numpy.ndarray or None, optional), default=None:

The confounding variables to be controlled for, i.e. regressed out from the input data. The array should have a shape (n, c), where n is the number of trials and c is the number of confounding variables. Each column represents a different confound to be controlled for in the analysis.

combine_tests (bool or str, optional), default=False:

Summarises multiple p-values using the Non-Parametric Combination (NPC) method for multivariate and univariate tests. - True: Returns a single p-value summarizing the entire test (1 × 1). - “across_rows”: Returns one p-value per outcome (1 × q). - “across_columns”: Returns one p-value per predictor (1 × p), only for univariate tests.

detect_categorical (bool), default=False:

If True, automatically detects categorical columns in R_data and applies the appropriate statistical test: - Multiclass categorical variables: ANOVA (F-test). - Continuous variables: F-regression for multivariate tests.

category_limit (int), default=10

Maximum number of unique values allowed to decide whether to use F-ANOVA or F-regression in the F-test. Prevents integer-valued variables (e.g., age) from being misclassified as categorical.

n_cca_components (int), default=1:

Number of Canonical Correlation Analysis (CCA) components to compute.

predictor_names (list of str, optional):

Names of the predictor variables in D_data (should match column order).

outcome_names (list of str, optional):

Names of the outcome variables in R_data.

return_base_statistics (bool, optional), default=True:

If True, stores test statistics from all permutations.

verbose (bool, optional):

If True, prints progress messages.

Returns:

result (dict):

The returned dictionary contains: ‘pval’: P-values for each test:

• “multivariate”: (T, q)

• “univariate”: (T, p, q)

• “cca”: (T, 1)

‘base_statistics’: Test statistics computed from the original/observed data (unpermuted). null_stat_distribution: Distribution of test statistics under the null hypothesis, where the first row always corresponds to the observed test statistic.

• “multivariate”: (T, Nnull_samples, q)

• “univariate”: (T, Nnull_samples, p, q)

• “cca”: (T, Nnull_samples, 1)

‘statistical_measures’: Dictionary mapping each column in the ‘q’ dimension of ‘null_stat_distribution’ to its corresponding unit. ‘test_type’: “test_across_sessions”. ‘method’: Analytical approach used (e.g., ‘multivariate’, ‘univariate’, ‘CCA’). ‘combine_tests’: Marks whether the Non-Parametric Combination (NPC) method was applied to summarise p-values (False/True/across_rows/across_columns. ‘max_correction’: Mraks whether FWER correction was applied (True/False). ‘Nnull_samples’: Number of samples used to generate the null distribution, obtained via permutation for permutation-based tests. ‘test_summary’: Dictionary summarising test results. ‘pval_f_multivariate’ (only if `method=”multivariate”` and `Nnull_samples > 1`): P-values from the F-test in the multivariate analysis. ‘pval_t_multivariate’ (only if `method=”multivariate”` and `Nnull_samples > 1`): P-values from the t-tests in the multivariate analysis.

glhmm.statistics.test_across_state_visits(D_data, R_data, method='multivariate', Nnull_samples=0, confounds=None, comparison_statistic='mean', state_comparison='larger', FWER_correction=False, detect_categorical=False, category_limit=10, vpath_surrogates=None, predictor_names=[], outcome_names=[], return_base_statistics=True, verbose=True)

Perform permutation testing across state visits.

This test assesses whether variations in an external signal (R_data) correspond to differences in state sequences (D_data) derived from the Viterbi path. For example, it can test whether physiological signals (e.g., pupil size, heart rate, or skin conductance in R_data) systematically vary depending on the brain state (D_data) during rest or task engagement.

Parameters:

D_data (numpy.ndarray):

Viterbi path data, provided as either a 1D or 2D array: - 1D: (n,), contains discrete state labels at each timepoint. where n is the number of timepoints and p is the number of predictors. - 2D: (n, K), One-hot encoded states at each timepoint. where n is the number of timepoints (or samples, no. of timepoints × no. of sessions), and K is the number of states.

R_data (numpy.ndarray):

Continuous physiological signal measurements - 2D: (n, q), where n is the number of timepoints (or samples, no. of timepoints × no. of sessions) and q is the number of recorded signals (e.g., pupil size, heart rate).

method (str, optional), default=”multivariate”:

The statistical method used to analyse the relationship between states from the Viterbi path and continuous signals. Valid options are: - “multivariate”: Tests whether a states from the Viterbi path explains variation in the signals. - “univariate”: Tests whether each state individually explains variation in the signals. - “cca”: Stands for Canonical Correlation Analysis; Identifies patterns of shared variation between the Viterbi path and signals, returning a single p-value indicating whether they are linked overall. - “osr”: Stands for One-State-vs-the-Rest; Compares one state against all others combined to assess its influence on the signal. - “osa” Stands for One-State-vs-Another-State; Compares differences between two selected states

Nnull_samples (int), default=0:

Number of generated Viterbi path surrogates used to generate the null distribution, obtained via Monte Carlo resampling. Set Nnull_samples=0 for parametric test output.

confounds (numpy.ndarray or None, optional), default=None:

The confounding variables to be controlled for, i.e. regressed out from R_data (signal measurements). The array should have a shape (n, c), where n is the number of trials and c is the number of confounding variables. Each column represents a different confound to be controlled for in the analysis.

comparison_statistic (str, optional, default=”mean”):

Statistic for “osr” and “osa” methods: - “mean”: Use the mean difference. - “median”: Use the median difference.

state_comparison (str, optional), default=”larger”:

Only applies to the “osr” test. Defines how the signal of a given state is compared to the average across other states: - “larger”: Tests whether the state has a larger signal than the rest. - “smaller”: Tests whether the state has a smaller signal than the rest.

FWER_correction (bool, optional), default=False:

If True, applies family-wise error rate (FWER) correction using the MaxT method to reduce false positives.

detect_categorical (bool), default=False:

If True, automatically detects categorical columns in R_data and applies the appropriate statistical test: - Binary categorical variables: Independent t-test. - Multiclass categorical variables: MANOVA for multivariate tests, ANOVA (F-test) for univariate test. - Continuous variables: F-regression for multivariate tests, Pearson’s t-test for univariate tests.

category_limit (int), default=10

Maximum number of unique values allowed to decide whether to use F-ANOVA or F-regression in the F-test. Prevents integer-valued variables (e.g., age) from being misclassified as categorical.

vpath_surrogates (numpy.ndarray, optional):

If provided, these surrogate sequences will be used instead of generating new ones. - 2D: (n, q), where n is the number of timepoints (or samples, no. of timepoints × no. of sessions), and `Nnull_samples`is the number of surrogate sequences generated.

predictor_names (list of str, optional):

Names of the predictor variables in D_data (should match column order).

outcome_names (list of str, optional):

Names of the outcome variables in R_data.

return_base_statistics (bool, optional), default=True:

If True, stores test statistics from all permutations.

verbose (bool, optional):

If True, prints progress messages.

Returns:

result (dict):

The returned dictionary contains: ‘pval’: P-values for each test:

• “multivariate”: (q,)

• “univariate”: (p, q)

• “cca”: (1)

• “osa”: (q,)

• “osr”: (p, p)

‘base_statistics’: Test statistics from original/observed data. null_stat_distribution: Distribution of test statistics under the null hypothesis, where the first row always corresponds to the observed test statistic.

• “multivariate”: (Nnull_samples, q)

• “univariate”: (Nnull_samples, p, q)

• “cca”: (Nnull_samples, 1)

• “osa”: (Nnull_samples, len(pairwise_comparisons), q)

• “osr”: (Nnull_samples, p, q)

‘test_type’: “test_state_subjects”. ‘method’: Chosen statistical method (“multivariate”, “univariate”,`”cca”, `”osa” or “osr”). ‘max_correction’: Marks whether FWER correction was applied (True/False). ‘Nnull_samples’: Number of generated Viterbi path surrogates used to generate the null distribution, obtained via Monte Carlo resampling. ‘test_summary’: Summary of test results. ‘pval_ftest_multivariate’ (only if `method=”multivariate”` and `Nnull_samples > 1`): P-values from the F-test in the multivariate analysis. ‘pval_ttest_multivariate’ (only if `method=”multivariate”` and `Nnull_samples > 1`): P-values from the t-tests in the multivariate analysis.

glhmm.statistics.test_across_subjects(D_data, R_data, method='multivariate', Nnull_samples=0, confounds=None, idx_data=None, permute_within_blocks=False, permute_between_blocks=False, dict_family=None, FWER_correction=False, combine_tests=False, detect_categorical=False, category_limit=10, n_cca_components=1, predictor_names=[], outcome_names=[], return_base_statistics=True, verbose=True)

Perform permutation testing across subjects.

This test assesses whether individual differences in predictor data (D_data) correspond to variations in behavioural or demographic measures (R_data). For example, it can test whether neural features (D_data) relate to cognitive scores, clinical assessments, or demographic factors (R_data), such as examining how brain activity patterns vary with age or cognitive performance across individuals.

Parameters:

D_data (numpy.ndarray):

Input data as a 2D array of shape (n, p), where: - n is the number of subjects. - p is the number of predictor variables.

R_data (numpy.ndarray):

Outcome data as a 2D array. - 2D: (n, q), where n is the number of subjects and q is the number of outcome variables.

method (str, optional), default=”multivariate”:

The statistical method to use for the permutation test. Valid options are: - “multivariate”: Examines whether multiple predictors (e.g., brain states) varies across individuals based on outcome measures (e.g., memory scores, clinical assessments). - “univariate”: Tests each predictor individually to assess whether it differs across subjects (e.g., whether time spent in a brain state is linked to cognitive performance). - ‘cca’: Stands for Canonical Correlation Analysis; Identifies patterns of shared variation between predictors and outcomes across subjects, returning a single p-value indicating whether they are linked overall.

Nnull_samples (int), default=0:

Number of samples used to generate the null distribution, obtained via permutation. Set Nnull_samples=0 for parametric test output.

confounds (numpy.ndarray or None, optional), default=None:

Variables to control for (e.g., age, gender). These will be removed from the predictor data before analysis. - Shape: (n, c), where c is the number of confounding variables.

idx_data (numpy.ndarray), default=None:

Used when permute_within_blocks=True and/or permute_between_blocks=True to define subject or session groupings for permutation. - 1D array: Specifies group labels for each subject or session (e.g., [1,1,1,2,2,2,…,N]). - 2D array: Defines trial boundaries for each session as a list of [start, end] index pairs (e.g., [[0, 50], [50, 100], [100, 150], …, [N_start, N_end]]).

permute_within_blocks (bool, optional), default=False:

If True, permutations happen only within predefined groups (e.g., subjects or sessions).

permute_between_blocks (bool, optional), default=False:

If True, permutations happen between different predefined groups.

dict_family (dict, optional):

Only needed when subjects have family relationships that must be accounted for in the permutation scheme. - Contains information about related individuals. - See PALM documentation: [PALM Exchangeability Blocks](https://web.mit.edu/fsl_v5.0.10/fsl/doc/wiki/PALM(2f)ExchangeabilityBlocks.html). If provided, this must include: - file_location (str): Path to the Exchangeable Block (EB) CSV-file with family structure information.

FWER_correction (bool, optional), default=False:

If True, applies family-wise error rate (FWER) correction using the MaxT method to reduce false positives.

combine_tests (bool or str, optional), default=False:

Summarises multiple p-values using the Non-Parametric Combination (NPC) method for multivariate and univariate tests. - True: Returns a single p-value summarizing the entire test (1 × 1). - “across_rows”: Returns one p-value per outcome (1 × q). - “across_columns”: Returns one p-value per predictor (1 × p), only for univariate tests.

detect_categorical (bool), default=False:

If True, automatically detects categorical columns in R_data and applies the appropriate statistical test: - Binary categorical variables: Independent t-test. - Multiclass categorical variables: MANOVA for multivariate tests, ANOVA (F-test) for univariate test. - Continuous variables: F-regression for multivariate tests, Pearson’s t-test for univariate tests.

category_limit (int), default=10

Maximum number of unique values allowed to decide whether to use F-ANOVA or F-regression in the F-test. Prevents integer-valued variables (e.g., age) from being misclassified as categorical.

n_cca_components (int), default=1:

Number of Canonical Correlation Analysis (CCA) components to compute.

predictor_names (list of str, optional):

Names of the predictor variables in D_data (should match column order).

outcome_names (list of str, optional):

Names of the outcome variables in R_data.

return_base_statistics (bool, optional), default=True:

If True, stores test statistics from all permutations.

verbose (bool, optional):

If True, prints progress messages.

Returns:

result (dict):

The returned dictionary contains: ‘pval’: P-values for each test:

• “multivariate”: (q,)

• “univariate”: (p, q)

• “cca”: (1)

‘base_statistics’: Test statistics computed from the original/observed data (unpermuted). null_stat_distribution: Distribution of test statistics under the null hypothesis, where the first row always corresponds to the observed test statistic.

• “multivariate”: (Nnull_samples, q)

• “univariate”: (Nnull_samples, p, q)

• “cca”: (Nnull_samples, 1)

‘statistical_measures’: Dictionary specifying the units used for each column in ‘null_stat_distribution’. ‘test_type’: “test_across_subjects”. ‘method’: Analytical approach used (e.g., ‘multivariate’, ‘univariate’, ‘CCA’). ‘combine_tests’: Marks whether the Non-Parametric Combination (NPC) method was applied to summarise p-values(False/True/across_rows/across_columns). ‘max_correction’: Marks whether FWER correction was applied (True/False). ‘Nnull_samples’: Number of samples used to generate the null distribution, obtained via permutation. ‘test_summary’: Dictionary summarising test results based on the selected method. ‘pval_f_multivariate’ (only if `method=”multivariate”` and `Nnull_samples > 1`): P-values from the F-test in the multivariate analysis. ‘pval_t_multivariate’ (only if `method=”multivariate”` and `Nnull_samples > 1`): P-values from the t-tests in the multivariate analysis.

glhmm.statistics.test_across_trials(D_data, R_data, idx_data, method='multivariate', Nnull_samples=0, confounds=None, FWER_correction=False, combine_tests=False, detect_categorical=False, category_limit=10, n_cca_components=1, predictor_names=[], outcome_names=[], return_base_statistics=True, verbose=True)

Perform permutation testing across different trials within a session.

This test assesses whether trial-to-trial variations in predictor data (D_data) correspond to differences in outcome data (R_data). For example, it can evaluate whether neural responses (D_data) differ depending on behavioural conditions (R_data), such as viewing an animate versus inanimate object.

Parameters:

D_data (numpy.ndarray):

Predictor data representing brain activity or other features. - 2D: (n, p), where n is the number of trials and p is the number of predictors. - 3D: (T, n, p), where T is the number of timepoints, n is the number of trials, and p is the number of predictors.

R_data (numpy.ndarray):

Outcome data representing behavioral responses or other dependent measures. - 2D: (n, q), where n is the number of trials and q is the number of outcome variables.

idx_data (numpy.ndarray):

Defines how trials are grouped into different sessions (e.g., trial type labels or session indices). - 1D array: Specifies group labels for each subject or session (e.g., [1,1,1,2,2,2,…,N]). - 2D array: Defines trial boundaries for each session as a list of [start, end] index pairs (e.g., [[0, 50], [50, 100], [100, 150], …, [N_start, N_end]]).

method (str, optional), default=”multivariate”:

The statistical method to use for the permutation test. Valid options are: - “multivariate”: Examines whether multiple predictors (e.g., brain states) varies across trial types. - “univariate”: Tests each predictor individually to assess whether it differs between trial types (e.g., whether specific brain states are different across conditions). - ‘cca’: Stands for Canonical Correlation Analysis; Identifies patterns of shared variation between predictors and outcomes across trials, returning a single p-value indicating whether they are linked overall.

Nnull_samples (int), default=0:

Number of samples used to generate the null distribution, obtained via permutation. Set Nnull_samples=0 for parametric test output.

FWER_correction (bool, optional), default=False:

If True, applies family-wise error rate (FWER) correction using the MaxT method to reduce false positives.

confounds (numpy.ndarray or None, optional), default=None:

The confounding variables to be controlled for, i.e. regressed out from the input data. The array should have a shape (n, c), where n is the number of trials and c is the number of confounding variables. Each column represents a different confound to be controlled for in the analysis.

combine_tests (bool or str, optional), default=False:

Summarises multiple p-values using the Non-Parametric Combination (NPC) method for multivariate and univariate tests. - True: Returns a single p-value summarizing the entire test (1 × 1). - “across_rows”: Returns one p-value per outcome (1 × q). - “across_columns”: Returns one p-value per predictor (1 × p), only for univariate tests.

detect_categorical (bool), default=False:

If True, automatically detects categorical columns in R_data and applies the appropriate statistical test: - Binary categorical variables: Independent t-test. - Multiclass categorical variables: MANOVA for multivariate tests, ANOVA (F-test) for univariate test. - Continuous variables: F-regression for multivariate tests, Pearson’s t-test for univariate tests.

category_limit (int), default=10

Maximum number of unique values allowed to decide whether to use F-ANOVA or F-regression in the F-test. Prevents integer-valued variables (e.g., age) from being misclassified as categorical.

n_cca_components (int), default=1:

Number of Canonical Correlation Analysis (CCA) components to compute.

predictor_names (list of str, optional):

Names of the predictor variables in D_data (should match column order).

outcome_names (list of str, optional):

Names of the outcome variables in R_data.

return_base_statistics (bool, optional), default=True:

If True, stores test statistics from all permutations.

verbose (bool, optional):

If True, prints progress messages.

Returns:

result (dict):

The returned dictionary contains: ‘pval’: P-values for each test:

• “multivariate”: (T, q)

• “univariate”: (T, p, q)

• “cca”: (T, 1)

‘base_statistics’: Test statistics computed from the original/observed data (unpermuted). null_stat_distribution: Distribution of test statistics under the null hypothesis, where the first row always corresponds to the observed test statistic.

• “multivariate”: (T, Nnull_samples, q)

• “univariate”: (T, Nnull_samples, p, q)

• “cca”: (T, Nnull_samples, 1)

‘statistical_measures’: Dictionary mapping each column in the ‘q’ dimension of ‘null_stat_distribution’ to its corresponding unit. ‘test_type’: “test_across_trials”. ‘method’: Analytical approach used (e.g., ‘multivariate’, ‘univariate’, ‘CCA’). ‘combine_tests’: Marks whether the Non-Parametric Combination (NPC) method was applied to summarise p-values (False/True/across_rows/across_columns. ‘max_correction’: Marks whether FWER correction was applied (True/False). ‘Nnull_samples’: ‘Nnull_samples’: Number of samples used to generate the null distribution, obtained via permutation. ‘test_summary’: Dictionary summarising test results based on the selected method. ‘pval_f_multivariate’ (only if `method=”multivariate”` and `Nnull_samples > 1`): P-values from the F-test in the multivariate analysis. ‘pval_t_multivariate’ (only if `method=”multivariate”` and `Nnull_samples > 1`): P-values from the t-tests in the multivariate analysis.

glhmm.statistics.test_statistics_calculations(Din, Rin, perm, test_statistics, reg_pinv, method, category_columns=[], combine_tests=False, idx_data=None, permute_beta=False, beta=None, test_indices=None, Nnull_samples=None, n_cca_components=1)

Computes test statistics and p-values based on permutation testing.

Parameters:

Din (numpy.ndarray):

Independent variable matrix (predictors).

Rin (numpy.ndarray):

Dependent variable matrix (responses).

perm (int):

Current permutation index.

test_statistics (numpy.ndarray):

Array storing computed test statistics for each permutation.

reg_pinv (numpy.ndarray or None):

Regularized pseudo-inverse of Din, if applicable.

method (str):

The permutation testing method used.

category_columns (dict), optional:

A dictionary marking the columns where t-test (“t_stat_independent_cols”) and F-test (“f_anova_cols”) have been applied.

combine_tests (str), default=False:

Specifies the method for combining test results. Valid options: “True”, “across_columns”, “across_rows”.

idx_data (numpy.ndarray), default=None:

Indexing array for session-based data.

permute_beta (bool), default=False:

If True, permutes beta coefficients.

beta (numpy.ndarray), default=None:

Beta coefficient matrix with shape (num_sessions, p, q), where: - num_sessions: Number of sessions. - p: Number of predictor features. - q: Number of dependent variables.

test_indices (numpy.ndarray), default=None:

Indices marking test-set data points for each session.

Nnull_samples (int), default=None:

Total number of permutations (if needed for normalization).

n_cca_components (int), default=1:

Number of Canonical Correlation Analysis (CCA) components to compute. Increasing this allows for capturing additional modes of covariance between Din and Rin.

Returns:

test_statistics (numpy.ndarray):

Updated array storing computed test statistics.

base_statistics (numpy.ndarray):

Raw statistics before permutation-based p-value computation.

pval_matrix (numpy.ndarray):

Parametric P-values derived from the different tests

glhmm.statistics.train_test_indices(Rin, Din, idx_data, method, category_limit=10)

Calculate beta for ordinary least squares regression.

Parameters:

reg_pinv (numpy.ndarray):

The regularized pseudo-inverse of D_data

Rin (numpy.ndarray):

Response matrix.

idx_data (numpy.ndarray):

Indices representing the start and end of trials.

nan_values (numpy.ndarray):

Whether to handle NaN values. Default is False.

Returns:

beta (numpy.ndarray):

Beta coefficients

test_indices_list (list)

glhmm.statistics.train_test_update_indices(train_indices_list, test_indices_list, nan_indices)

Update train and test indices after removing specified NaN indices and re-indexing the remaining values.

Parameters:

train_indices_list (list of list of int):

A list where each element is a list of sorted train indices for different segments.

test_indices_list (list of list of int):

A list where each element is a list of sorted test indices for different segments.

nan_indices (numpy.ndarray):

A list of indices to be removed from both train and test lists.

Returns:

train_indices_list_update (list of list of int):

The updated train indices with specified NaN indices removed and remaining indices re-indexed.

test_indices_list_update (list of list of int):

The updated test indices with specified NaN indices removed and remaining indices re-indexed.

glhmm.statistics.update_indices(nan_mask, idx_data)

Updates the index array to account for removed NaN values.

Parameters: nan_mask (np.ndarray):

A boolean array where True indicates NaN positions.

idx_data (np.ndarray):

A 2D array of shape (n, 2) where each row contains [start, end] indices.

Returns: idx_data_update (np.ndarray):

A 2D array of updated indices after removing NaN values.

glhmm.statistics.update_permutation_matrix(permutation_matrix, nan_mask)

Updates a permutation matrix by removing NaN indices and adjusting remaining indices.

Parameters:

permutation_matrix (numpy.ndarray):

A 2D array where each column represents a permutation.

nan_mask (numpy.ndarray):

A boolean array indicating positions of NaN values in the original dataset.

Returns:

updated_permutation_matrix (numpy.ndarray):

A 2D array with NaN indices removed and the remaining indices adjusted accordingly.

glhmm.statistics.validate_condition(condition, error_message)

Validates a given condition and raises a ValueError with the specified error message if the condition is not met.

Parameters:

condition (bool):

The condition to check.

error_message (str):

The error message to raise if the condition is not met.

glhmm.statistics.viterbi_path_to_stc(viterbi_path, n_states)

Convert Viterbi path to state-time matrix.

Parameters:

viterbi_path (numpy.ndarray):

1D array or 2D matrix containing the Viterbi path.

n_states (int):

Number of states in the hidden Markov model.

Returns:

stc (numpy.ndarray):

State-time matrix where each row represents a time point and each column represents a state.

glhmm.statistics.vpath_check_2D(vpath)

Validate whether a 2D matrix of the Viterbi path is one-hot encoded or if a 1D array contains integers.

Parameters:

vpath (numpy.ndarray):

A numpy array that can be either 2D or 1D.

Returns:

bool:

Returns True if the following conditions are met: - For a 2D array: The array is one-hot encoded, meaning each row contains exactly one ‘1’

(or 1.0) and all other elements are ‘0’ (or 0.0).

• For a 1D array: The array contains only integer values.

Returns False if any of these conditions are not satisfied.

Example:

# Example 1: 2D one-hot encoded array matrix = np.array([[0, 1, 0], [1, 0, 0], [0, 0, 1]]) vpath_check_2D(matrix) output: True

# Example 2: 1D integer array array = np.array([1, 2, 1, 0]) vpath_check_2D(array) output: True