Welcome to hyperit’s documentation!

Contents:

class hyperit.hyperit.HyperIT(data1: ndarray, data2: ndarray, channel_names: List[str] = None, standardise_data: bool = False, verbose: bool = False, show_tqdm: bool = True)[source]

Bases: object

HyperIT: Hyperscanning Analyses using Information Theoretic Measures.

HyperIT is equipped to compute pairwise and multivariate Mutual Information (MI), Transfer Entropy (TE), and Integrated Information Decomposition (ΦID) for continuous time-series data. Compatible for both intra-brain and inter-brain analyses and for both epoched and unepoched data.

Multiple estimator choices and parameter customisations (via JIDT) are available, including Histogram/Binning, Gaussian, Kernel, KSG, and Symbolic.

Integrated statistical significance testing using permutation/boostrapping approach.

Visualisations of MI/TE matrices also provided.

Parameters:

  • data1 (np.ndarray) – Time-series data for participant 1. Can take shape (n_epo, n_chan, n_samples) or (n_chan, n_samples) for epoched and unepoched data, respectively.

  • data2 (np.ndarray) – Time-series data for participant 2. Must have the same shape as data1.

  • channel_names (List[str], optional) – A list of strings representing the channel names for each participant. [[channel_names_p1], [channel_names_p2]] or [[channel_names_p1]].

  • standardise_data (bool, optional) – Whether to standardise the data before analysis. Defaults to True.

  • verbose (bool, optional) – Whether constructor and analyses should output details and progress. Defaults to False.

  • show_tqdm (bool, optional) – Whether to show tqdm progress bars. Defaults to True.

Note

This class requires numpy, mne, matplotlib, jpype (with the local infodynamics.jar file), and phyid as dependencies.

Before a HyperIT can be created, users must first call HyperIT.setup_JVM() to initialise the Java Virtual Machine (JVM) with the local directory location of the infodynamics.jar file. Users can then create multiple HyperIT objects containing time-series data, later calling various functions for analysis.

Automatic data checks for consistency and dimensionality, identifying whether analysis is to be intra- or inter-brain and epochality of data.

  • If data is 3 dimensional, data is assumed to be epoched with shape (epochs, channels, time_points).

  • If data is 2 dimensional, data is assumed to be unepoched with shape (channels, time_points).

  • If data is 1 dimensional, data is assumed to be single channel time series with shape (time_points).

compute_atoms(tau: int = 1, redundancy: str = 'MMI', include_intra: bool = False, epoch_average: bool = True) → Tuple[ndarray, ndarray][source]

Function to compute Integrated Information Decomposition (ΦID) between data (time-series signals) instantiated in the HyperIT object.

Parameters:

  • tau (int, optional) – Time-lag parameter. Defaults to 1.

  • redundancy (str, optional) – Redundancy function to use. Defaults to ‘MMI’ (Minimum Mutual Information).

  • include_intra (bool, optional) – Whether to include intra-brain analysis. Defaults to False.

  • epoch_average (bool, optional) – If True, results are averaged across epochs. Defaults to True.

Returns:

A matrix of integrated information decomposition atoms. The shape of the matrix is determined by the include_intra, epoch_average, and calc_statsig flags:

  • If include_intra is False, shape is (…, n_chan, n_chan, …).

  • If include_intra is True, shape is (…, 2*n_chan, 2*n_chan, …).

  • If epoch_average is True, shape is (n_chan, n_chan, …) or (2*n_chan, 2*n_chan, …).

  • If epoch_average is False, shape is (n_epo, n_chan, n_chan, …) or (n_epo, 2*n_chan, 2*n_chan, …).

  • If calc_statsig is True, an additional last dimension (size 4) contains statistical significance results: [MI value, mean, standard deviation, p-value].

Return type:

np.ndarray

Note

When include_intra is True, the matrix can be segmented accordingly:

  • intra1: matrix[:, :, :n_chan, :n_chan]

  • intra2: matrix[:, :, n_chan:, n_chan:]

  • inter12: matrix[:, :, :n_chan, n_chan:]

  • inter21: matrix[:, :, n_chan:, :n_chan]

Visualisation is not a possibility at the moment.

Available Redundancy Functions:

  • ‘MMI’: Minimum Mutual Information

  • ‘CCS’: Common Change in Surprisal

compute_mi(estimator: str = 'gaussian', include_intra: bool = False, epoch_average: bool = True, calc_statsig: bool = False, stat_sig_perm_num: int = 100, p_threshold: float = 0.05, vis: bool = False, plot_epochs: List[int] = None, **kwargs) → ndarray[source]

Computes Mutual Information (MI) between data (time-series signals) using specified estimator.

Parameters:

  • estimator (str, optional) – Specifies the MI estimator to use. Defaults to ‘gaussian’.

  • include_intra (bool, optional) – If True, includes intra-brain analyses. Defaults to False.

  • epoch_average (bool, optional) – If True, results are averaged across epochs. Defaults to True.

  • calc_statsig (bool, optional) – If True, performs statistical significance testing. Defaults to False.

  • stat_sig_perm_num (int, optional) – Number of permutations for statistical significance testing. Defaults to 100.

  • p_threshold (float, optional) – Threshold for statistical significance testing. Defaults to 0.05.

  • vis (bool, optional) – If True, results will be visualised. Defaults to False.

  • plot_epochs (List[int], optional) – Specifies which epochs to plot. None plots all. Defaults to None.

  • **kwargs – Additional keyword arguments for MI estimators.

Returns:

A symmetric mutual information matrix. The shape of the matrix is determined by the include_intra, epoch_average, and calc_statsig flags:

  • If include_intra is False, shape is (…, n_chan, n_chan, …).

  • If include_intra is True, shape is (…, 2*n_chan, 2*n_chan, …).

  • If epoch_average is True, shape is (n_chan, n_chan, …) or (2*n_chan, 2*n_chan, …).

  • If epoch_average is False, shape is (n_epo, n_chan, n_chan, …) or (n_epo, 2*n_chan, 2*n_chan, …).

  • If calc_statsig is True, an additional last dimension (size 4) contains statistical significance results: [MI value, mean, standard deviation, p-value].

Return type:

np.ndarray

Note

When include_intra is True, the matrix can be segmented accordingly:

  • intra1: matrix[:, :, :n_chan, :n_chan]

  • intra2: matrix[:, :, n_chan:, n_chan:]

  • inter12: matrix[:, :, :n_chan, n_chan:]

  • inter21: matrix[:, :, n_chan:, :n_chan]

Available Estimators and Their Parameters:
  • histogram:

    • None.

  • ksg1:

    • kraskov_param (int, default=4).

    • normalise (bool, default=True).

  • ksg2:

    • kraskov_param (int, default=4).

    • normalise (bool, default=True).

  • kernel:

    • kernel_width (float, default=0.25).

    • normalise (bool, default=True).

  • gaussian:

    • normalise (bool, default=True).

  • symbolic:

    • k (int, default=3): Embedding history or symbol length.

    • delay (int, default=1).

compute_te(estimator: str = 'gaussian', include_intra: bool = False, epoch_average: bool = True, calc_statsig: bool = False, stat_sig_perm_num: int = 100, p_threshold: float = 0.05, vis: bool = False, plot_epochs: List[int] = None, **kwargs) → ndarray[source]

Computes Transfer Entropy (TE) between time-series data using a specified estimator. This function allows for intra-brain and inter-brain analyses and includes optional statistical significance testing. Data1 is considered the source and Data2 the target.

Parameters:

  • estimator (str, optional) – Specifies the TE estimator to use. Defaults to ‘gaussian’.

  • include_intra (bool, optional) – Whether to include intra-brain comparisons in the output matrix. Defaults to False.

  • epoch_average (bool, optional) – If True, results are averaged across epochs. Defaults to True.

  • calc_statsig (bool, optional) – Whether to calculate statistical significance of TE values. Defaults to False.

  • stat_sig_perm_num (int, optional) – Number of permutations for statistical significance testing. Defaults to 100.

  • p_threshold (float, optional) – Threshold for statistical significance testing. Defaults to 0.05.

  • vis (bool, optional) – Enables visualisation of the TE matrix if set to True. Defaults to False.

  • plot_epochs (List[int], optional) – Specifies which epochs to plot. If None, plots all epochs. Defaults to None.

  • **kwargs – Additional parameters for TE estimators.

Returns:

A transfer entropy matrix. The shape of the matrix is determined by the include_intra, epoch_average, and calc_statsig flags:

  • If include_intra is False, shape is (…, n_chan, n_chan, …).

  • If include_intra is True, shape is (…, 2*n_chan, 2*n_chan, …).

  • If epoch_average is True, shape is (n_chan, n_chan, …) or (2*n_chan, 2*n_chan, …).

  • If epoch_average is False, shape is (n_epo, n_chan, n_chan, …) or (n_epo, 2*n_chan, 2*n_chan, …).

  • If calc_statsig is True, an additional last dimension (size 4) contains statistical significance results: [MI value, mean, standard deviation, p-value].

Return type:

np.ndarray

Note

When include_intra is True, the matrix can be segmented accordingly:

  • intra1: matrix[:, :, :n_chan, :n_chan]

  • intra2: matrix[:, :, n_chan:, n_chan:]

  • inter12: matrix[:, :, :n_chan, n_chan:]

  • inter21: matrix[:, :, n_chan:, :n_chan]

Available Estimators and Their Parameters:
  • ksg:

    • k, k_tau (int, default=1): Target and source embedding history length.

    • l, l_tau (int, default=1): Target and source embedding delay.

    • delay (int, default=1): Delay parameter for temporal dependency.

    • kraskov_param (int, default=1).

    • normalise (bool, default=True).

  • kernel:

    • kernel_width (float, default=0.5).

    • delay (int, default=1)

    • normalise (bool, default=True).

  • gaussian:

    • k, k_tau (int, default=1): Target and source embedding history length.

    • l, l_tau (int, default=1): Target and source embedding delay.

    • delay (int, default=1): Delay parameter for temporal dependency.

    • bias_correction (bool, default=False).

    • normalise (bool, default=True).

  • symbolic:

    • k (int, default=1): Embedding history length.

    • normalise (bool, default=True).

reset_roi() → None[source]

Resets the region of interest for both data of the HyperIT object to all channels.

property roi: List[List[str | int | list]]

Regions of interest for both data of the HyperIT object (defining spatial scale of organisation). To set this, call .roi(roi_list).

HyperIT is defaulted to micro-scale analysis (individual channels) but specific channels can be specified for pointwise comparison: roi_list = [['Fp1', 'Fp2'], ['F3', 'F4']], for example. For meso-scale analysis (clusters of channels), equally-sized and equally-numbered clusters must be defined for both sets of data in the following way: roi_list = [[[PP1_cluster_1], ..., [PP1_cluster_n]], [[PP2_cluster_1], ..., [PP2_cluster_n]]]. Finally, for macro-scale analysis (all channels per person), the specification can be set as roi_list = [[PP1_all_channels][PP2_all_channels]] (note that PP1_all_channels and PP2_all_channels should be list themselves). Importantly, as long as the channel_names are instantiated properly in the initiation of the HyperIT object, the ROI can even be given as a lists of channel indices (integers). In any case, to set these scales of organisations, simply amend the roi property of the HyperIT object used. Call roi.reset_roi() to reset the ROI to all channels.

classmethod setup_JVM(verbose: bool = False) → None[source]

Setup JVM if not already started. To be called once before creating any instances.

class hyperit.hyperit.MeasureType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

MI = 'mi'
PhyID = 'phyid'
TE = 'te'

Indices and tables