Quickstart

HOI is a Python package to estimate Higher Order Interactions from multivariate data. A network is composed of nodes (e.g. users in social network, brain areas in neuroscience, musicians in an orchestra etc.) and nodes are interacting together. Traditionally we measure pairwise interactions. HOI allows to go beyond the pairwise interactions by quantifying the interactions between 3, 4, …, N nodes of the system. As we are using measures from the Information Theory, we can further describe the type of interactions, i.e. whether nodes of the network tend to have redundant or synergistic interactions (see the definition of Redundancy, Synergy).

• Installation : to install HOI with its dependencies, see Installation. If you are a developer or if you want to contribute to HOI, checkout the Developer Documentation.

• Theoretical background : For a detailed introduction to information theory and HOI, see Theoretical background. You can also have a look to our Glossary to see the definition of the terms we are using here.

• API and examples : the list of functions and classes can be found in the section List of classes and functions. For practical examples on how to use those functions, see Examples. For faster computations, HOI is built on top of Jax. Checkout the page Jax: linear algebra backend for the performance claims.

Installation

To install or update HOI, run the following command in your terminal :

pip install -U hoi

Simulate data

We provide functions to simulate data and toy example. In a notebook or in a python script, you can run the following lines to simulate synergistic interactions between three variables :

from hoi.simulation import simulate_hoi_gauss

data = simulate_hoi_gauss(n_samples=1000, triplet_character='synergy')

Compute Higher-Order Interactions

We provide a list of metrics of HOI (see hoi.metrics). Here, we are going to use the O-information (hoi.metrics.Oinfo):

# import the O-information
from hoi.metrics import Oinfo

# define the model
model = Oinfo(data)

# compute hoi for multiplets with a minimum size of 3 and maximum size of 3
# using the Gaussian Copula entropy
hoi = model.fit(minsize=3, maxsize=3, method="gc")

Inspect the results

To inspect your results, we provide a plotting function called hoi.plot.plot_landscape() to see how the information is spreading across orders together with hoi.utils.get_nbest_mult() to get a table of the multiplets with the strongest synergy or redundancy :

from hoi.plot import plot_landscape
from hoi.utils import get_nbest_mult

# plot the landscape
plot_landscape(hoi, model=model)

# print the summary table
print(get_nbest_mult(hoi, model=model))

Practical recommendations

Robust estimations of HOI strongly rely on the acuity of measuring entropy/mutual information on/between (potentially highly) multivariate data. In the Examples section you can find benchmarks of our entropy estimators. Here we recommend :

• Measuring entropy and mutual information : we recommend the Gaussian Copula method (method=”gc”). Although this measure is not accurate for capturing relationships beyond the gaussian assumption (see Comparison of entropy estimators for various distributions), this method performs relatively well for multivariate data (see Comparison of entropy estimators for a multivariate normal)

• Measuring Higher-Order Interactions for network behavior and network encoding : for network behavior and encoding, we recommend respectively the O-information hoi.metrics.Oinfo and the hoi.metrics.GradientOinfo. Although both metrics suffer from the same limitations, like the spreading to higher orders, this can be mitigated using a bootstrap approach (see Bootstrapping and confidence interval). Otherwise, both metrics are usually pretty accurate to retrieve the type of interactions between variables, especially once combined with the Gaussian Copula.

Other softwares for the analysis of higher-order interactions

Please find bellow a list of additional softwares for the analysis of higher-order interactions :

• XGI : Python software for modeling, analyzing, and visualizing higher-order interactions

• NetworkX : Python package for the creation, manipulation, and study of the structure, dynamics, and functions of complex networks

• TopoNetX : Python package for computing on topological domains

• HGX : Python library for higher-order network analysis

• InfoTopo : original Python implementation of the hoi.metrics.InfoTopo estimator

• infotheory : C++, and usable in Python as well, Infotheory is a software to perform information theoretic analysis on multivariate data

• dit : Python package for discrete information theory

• IDTxl : Python software for efficient inference of networks and their node dynamics from multivariate time series data using information theory

• pyphi : Python library for computing integrated information