From 80896c087063421e7d64fcfa8ceb4b883cc434ae Mon Sep 17 00:00:00 2001 From: EtienneCmb Date: Fri, 5 Jul 2024 13:21:35 +0200 Subject: [PATCH] Add quickstart --- docs/_templates/layout.html | 5 +-- docs/api/api_metrics.rst | 2 ++ docs/conf.py | 4 +-- docs/contributor_guide.rst | 2 ++ docs/glossary.rst | 2 ++ docs/jax.rst | 3 +- docs/quickstart.rst | 68 +++++++++++++++++++++++++++++++++-- docs/theory.rst | 2 ++ examples/it/plot_entropies.py | 4 +-- 9 files changed, 82 insertions(+), 10 deletions(-) diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index cb25fce0..3c015a09 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -23,10 +23,11 @@ {% endblock %} \ No newline at end of file diff --git a/docs/api/api_metrics.rst b/docs/api/api_metrics.rst index 9848a312..433d8eeb 100644 --- a/docs/api/api_metrics.rst +++ b/docs/api/api_metrics.rst @@ -1,3 +1,5 @@ +.. _metrics: + ``hoi.metrics`` --------------- diff --git a/docs/conf.py b/docs/conf.py index 6f2bb27b..267c1e15 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,8 +16,8 @@ sys.path.insert(0, os.path.abspath("..")) project = "HOI" -copyright = "BraiNets" -author = "BraiNets" +# copyright = "BraiNets" +# author = "BraiNets" release = hoi.__version__ release = hoi.__version__ diff --git a/docs/contributor_guide.rst b/docs/contributor_guide.rst index 17976245..1fc652b6 100644 --- a/docs/contributor_guide.rst +++ b/docs/contributor_guide.rst @@ -1,3 +1,5 @@ +.. _contribute: + Developer Documentation ======================= diff --git a/docs/glossary.rst b/docs/glossary.rst index a0008dbc..fbbf9c26 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1,3 +1,5 @@ +.. _glossary: + Glossary ======== diff --git a/docs/jax.rst b/docs/jax.rst index f72def5a..db79b081 100644 --- a/docs/jax.rst +++ b/docs/jax.rst @@ -128,5 +128,4 @@ Let's plot the results : .. image:: _static/jax_cgpu_oinfo.png -On this toy example, we can see that computing the O-information is ~3x faster -on GPU than on CPU. +On this toy example, computing the O-information on CPU takes ~13 seconds for each order while on GPU it takes ~3 seconds. GPU computations are ~4 times faster than CPU ! diff --git a/docs/quickstart.rst b/docs/quickstart.rst index d08e2c68..4a544183 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,7 +1,71 @@ Quickstart ========== +HOI is a Python package to estimate :term:`Higher Order Interactions`. 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 :term:`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 :term:`Redundancy`, :term:`Synergy`). + +* **Installation :** to install HOI with its dependencies, see :ref:`installation`. If you are a developer or if you want to contribute to HOI, checkout the :ref:`contribute`. +* **Theoretical background :** For a detailed introduction to information theory and HOI, see :ref:`theory`. You can also have a look to our :ref:`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 :ref:`hoi_modules`. For practical examples on how to use those functions, see :doc:`auto_examples/index`. For faster computations, HOI is built on top of Jax. Checkout the page :doc:`jax` for the performance claims. + +Installation +++++++++++++ + +To install or update HOI, run the following command in your terminal : + +.. code-block:: bash + + 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 : + +.. code-block:: python + + 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 :ref:`metrics`). Here, we are going to use the O-information (:class:`hoi.metrics.Oinfo`): + .. code-block:: python - # this is a comment - x = 2 \ No newline at end of file + # 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 :func:`hoi.plot.plot_landscape` to see how the information is spreading across orders together with :func:`hoi.utils.get_nbest_mult` to get a table of the multiplets with the strongest synergy or redundancy : + + +.. code-block:: python + + 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 accuity of measuring entropy/mutual information on/between (potentially highly) multivariate data. In the :doc:`auto_examples/index` 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 :ref:`sphx_glr_auto_examples_it_plot_entropies.py`), this method performs relatively well for multivariate data (see :ref:`sphx_glr_auto_examples_it_plot_entropies_mvar.py`) +* **Measuring Higher-Order Interactions for network behavior and network encoding :** for network behavior and ncoding, we recommend respectively the O-information :class:`hoi.metrics.Oinfo` and the :class:`hoi.metrics.GradientOinfo`. Although both metrics suffer from the same limitations, like the spreading to higher orders, this can be mitigated using a boostrap approach (see :ref:`sphx_glr_auto_examples_statistics_plot_bootstrapping.py`). Otherwise, both metrics are usually pretty accurate to retrieve the type of interactions between variables, especially once combined with the Gaussian Copula. diff --git a/docs/theory.rst b/docs/theory.rst index 54a22109..af68d8ae 100644 --- a/docs/theory.rst +++ b/docs/theory.rst @@ -1,3 +1,5 @@ +.. _theory: + Theoretical background ====================== diff --git a/examples/it/plot_entropies.py b/examples/it/plot_entropies.py index 2b887951..396c1cf6 100644 --- a/examples/it/plot_entropies.py +++ b/examples/it/plot_entropies.py @@ -1,6 +1,6 @@ """ -Comparison of entropy estimators -================================ +Comparison of entropy estimators for various distributions +========================================================== In this example, we are going to compare entropy estimators. In particular, some distributions, such as normal, uniform or exponential distributions lead