How brainets/hoi works
1. What this repo is
HOI is a Python scientific library for computing higher-order information-theoretic measures: not just pairwise dependence, but interactions among 2+ variables. The package is designed as a computation-oriented library, not a service or application.
2. Top-level architecture
The codebase is organized into a small set of domain-focused packages: hoi.core for mathematical primitives, hoi.metrics for user-facing HOI measures, hoi.simulation for synthetic data generation, hoi.plot for visualization, and hoi.utils for shared helpers.
3. Core mathematical layer
hoi.core contains the low-level building blocks used throughout the library: combinatorial subset handling, entropy estimation, mutual information, and redundancy-related primitives. This is the most fundamental dependency layer; the rest of the package composes these functions rather than reimplementing them.
4. Metric implementations as the main public API
hoi.metrics is the main feature layer. It includes implementations of many HOI measures such as total correlation, dual total correlation, O-information, S-information, redundancy/synergy metrics, PID/phiID atoms, pairwise MI, information topology, and transfer entropy. base_hoi.py suggests a shared abstraction or base class used by multiple metric modules.
5. Data flow for a typical computation
A user passes data into a metric class/function in hoi.metrics. That metric then relies on hoi.core to enumerate variable combinations and compute entropies or mutual information, and finally returns the higher-order score(s). In other words: raw data → core information primitives → derived HOI metric.
6. Simulation subsystem
hoi.simulation.simulate_hoi_gauss provides synthetic Gaussian data for experiments, demonstrations, and validation. This is important because many examples and tests likely depend on controlled synthetic datasets to verify metric behavior.
7. Visualization subsystem
hoi.plot.landscape provides plotting utilities for analyzing metric landscapes and interaction structure. This layer is separate from the computation layer, so visualization is treated as an output/analysis concern rather than part of the metric algorithms.
8. Shared utilities
hoi.utils holds cross-cutting helpers such as logging, multi-core support, progress bars, and statistical utilities. These are infrastructure-like concerns that support long-running metric computations and reproducible analysis without being specific to any one measure.
9. JAX-centered runtime model
The package is built on JAX, which is a key architectural choice: it enables accelerated numerical computation on CPU or GPU and shapes how the numerical kernels are written. NumPy/SciPy remain part of the broader scientific stack, while JAX is the execution backend that distinguishes this library.
10. Examples and documentation as architecture validation
The examples/ tree is grouped by use case: tutorial-style usage, information-theoretic computations, metric-specific examples, statistics, and miscellaneous demos. The docs/ tree mirrors the package structure with API pages, theory, installation, and quickstart material, so documentation is tightly aligned with the code architecture.
11. Testing and quality boundaries
Each major code area has its own tests under hoi/core/tests, hoi/metrics/tests, hoi/simulation/tests, and hoi/utils/tests. This indicates a modular boundary: core math, metric logic, synthetic data generation, and utilities are validated independently.
12. Packaging and release pipeline
The repository is a standard Python package with pyproject.toml, setup.py, and CI workflows for linting, tests, docs, and PyPI publishing. That means the main architectural boundary is the library API itself; build and release concerns are kept outside the runtime package.
Main entry points: metrics/__init__.py Metrics · core/__init__.py Core · modules.rst API refs · hoi/__init__.py hoi
Components 22
Library
Core importable HOI package and its main subsystems.
- hoi · Top-level HOI package entry point.
hoi/__init__.py - Core · Lowest-level information-theoretic building blocks.
hoi/core/__init__.py - Combinatory · Variable subset and combination handling.
hoi/core/combinatory.py - Entropies · Entropy estimation and related primitives.
hoi/core/entropies.py - MI · Mutual information computations used by metrics.
hoi/core/mi.py - Redundancies · Redundancy-related information primitives.
hoi/core/redundancies.py - Metrics · User-facing higher-order information measures.
hoi/metrics/__init__.py - Base HOI · Shared abstraction for metric implementations.
hoi/metrics/base_hoi.py - O-info · O-information and related decompositions.
hoi/metrics/oinfo.py - S-info · S-information measure implementation.
hoi/metrics/sinfo.py - TC / DTC · Total correlation and dual total correlation.
hoi/metrics/tc.py - PID atoms · Partial information decomposition atoms.
hoi/metrics/pid_atoms.py - phiID atoms · PhiID atom computation and redundancy variants.
hoi/metrics/phiid_atoms.py - InfoTopo · Information topology analysis utilities.
hoi/metrics/infotopo.py - Transfer Entropy · Transfer entropy computation.
hoi/metrics/transfer_entropy.py - Gaussian Sim · Synthetic Gaussian HOI data generation.
hoi/simulation/simulate_hoi_gauss.py - Landscape Plot · Plotting for metric landscapes and interaction structure.
hoi/plot/landscape.py - Utils · Shared logging, parallelism, progress, and stats helpers.
hoi/utils/__init__.py
Docs
Documentation and usage material aligned with the package structure.
Examples
Executable examples organized by use case.
- Examples · Example entry points and grouped demos.
examples/README.txt
Tooling
Packaging, CI, and repository-level build/release support.
- CI / Release · Packaging, linting, testing, and PyPI publishing workflows.
.github/workflows/test_doc.yml
Connections 31
- hoi → Core: imports · Top-level package exposes the core layer.
- hoi → Metrics: imports · Top-level package exposes the metrics API.
- hoi → Gaussian Sim: imports · Top-level package exposes simulation utilities.
- hoi → Landscape Plot: imports · Top-level package exposes plotting utilities.
- hoi → Utils: imports · Top-level package exposes shared helpers.
- Metrics → Base HOI: shared base · Metric modules share a common abstraction.
- Metrics → O-info: contains · Main HOI measure implementations.
- Metrics → S-info: contains · Main HOI measure implementations.
- Metrics → TC / DTC: contains · Main HOI measure implementations.
- Metrics → PID atoms: contains · Main HOI measure implementations.
- Metrics → phiID atoms: contains · Main HOI measure implementations.
- Metrics → InfoTopo: contains · Main HOI measure implementations.
- Metrics → Transfer Entropy: contains · Main HOI measure implementations.
- O-info → Core: uses core · Derived metrics depend on entropy and combinatorics.
- TC / DTC → Core: uses core · Core primitives power correlation-style measures.
- PID atoms → Core: uses core · Decomposition metrics depend on low-level primitives.
- phiID atoms → Core: uses core · Decomposition metrics depend on low-level primitives.
- InfoTopo → Core: uses core · Topology metrics are built on core information routines.
- Transfer Entropy → Core: uses core · Temporal information measures use the same primitives.
- Gaussian Sim → Metrics: feeds · Synthetic data supports metric experiments and validation.
- Landscape Plot → Metrics: visualizes · Plots analyze metric outputs and landscapes.
- Docs → API refs: organizes · Documentation hub points to the API reference.
- API refs → Core: documents · Reference mirrors the core package.
- API refs → Metrics: documents · Reference mirrors the metrics package.
- API refs → Gaussian Sim: documents · Reference mirrors the simulation package.
- API refs → Landscape Plot: documents · Reference mirrors the plot package.
- API refs → Utils: documents · Reference mirrors the utilities package.
- Examples → Metrics: demonstrates · Examples showcase metric usage.
- Examples → Gaussian Sim: demonstrates · Examples use synthetic data generation.
- CI / Release → hoi: builds/tests · Workflows validate the library package.
- CI / Release → Docs: docs · Workflows build and validate documentation.