Jacobian Geometry

A modular Python package for analyzing how network-driven dynamics induce mesoscale organization, through Jacobian-based and diffusion-based functional distances.

Based on the paper:

Giacomo Barzon, Oriol Artime, Samir Suweis, and Manlio De Domenico Unraveling the mesoscale organization induced by network-driven dynamics, PNAS 2024. https://www.pnas.org/doi/10.1073/pnas.2317608121 and the code is based on the original repository: https://github.com/gbarzon/jacobian_geometry

---

Getting Started

Install the package locally:

pip install -e .

The Jacobian distance

Let us consider a networked dynamical system $$\dot{x}_k = f_k(x_1, \ldots, x_N) \equiv f_k(\mathbf{x}),$$ where $x_k(t)$ is a variable representing the state of node $k = 1, \ldots, N$ at time $t$. The steady state $\mathbf{x}^{*}$ of the system is given by $f_k(\mathbf{x}^{*}) = 0 \ \forall k$. The time evolution of the perturbation on any node $k$ follows, then, $$\delta \dot{x}_k(t) = f_k( \mathbf{x}^* + \delta \mathbf{x}(t)).$$

In vectorial notation, we have that $\delta \mathbf{x} _{(i)}(0) = \delta x_i \mathbf{e} _{i}$, where $\mathbf{e}_{i}$ is the unitary vector in the $i$-direction, and $$\delta \dot{\mathbf{x}}_{(i)} (t) = \mathrm{J} (\mathbf{x}^{*}) \delta \mathbf{x}_{(i)}(t), $$ where $\mathrm{J}(\mathbf{x}^{*})$ is the Jacobian matrix evaluated at the steady state, which in general depends both on the specific functional form of the vector fields $\mathbf{f}$ and the topology. The general solution is given by $$\delta \mathbf{x}_{(i)}(t) = e^{\mathrm{J}(\mathbf{x}^*) t} \delta \mathbf{x}_{(i)}(0).$$

The Jacobian distance is then defined as the temporal evolution of the difference between two perturbations of intensity $\delta x_i$ and $\delta x_j$ initially placed in nodes $i$ and $j$

$$d_\tau(i,j) = || \delta \mathbf{x}_{(i)}(\tau) - \delta \mathbf{x}_{(j)}(\tau) || \\\ = || e^{\mathrm{J}(\mathbf{x}^*) \tau} [\delta x_i \mathbf{e}_{i} - \delta x_j \mathbf{e}_{j}] ||$$

Since we are interested in unveiling the emergent patterns that are most persistent at the mesoscale, it is natural to average the distance matrices,

$$\overline{d}(i,j) = \frac{1}{\tau_{\text{max}}}\sum_{\tau=1}^{\tau_{\text{max}}} d_\tau(i,j),$$

up to a certain cutoff that we fix $\tau_{\text{max}} \approx N$. In this way, emergent mesoscale patterns, if any, are highlighted.

How to compute the Jacobian distance

### Import utils functions
import jacobian_geometry

### Get the network
# E.g., generate a hierarchical modular network
from galib.models import HMRandomGraph
N = 128
HMshape = [2,2,32]
avklist = [1,3,20]
mat = HMRandomGraph(HMshape, avklist)

### Define the dynamical process
dynamic = 'Epidemics'

### Define the dynamical parameters
B = 1.
R = 0.05
params = [B, R]
    
### Compute jacobian distance at various tau
# avg_jacobian_distance: matrix of the pairwise jacobian distance
# linkage: hierarchical clustering encoded as a linkage matrix (see scipy.cluster.hierarchy.linkage)
avg_jacobian_distance, _, linkage, jacobian = jacobian_geometry.jacobian_distance(mat, dynamic, args=params, norm=True, show=True)

Implemented dynamical processes

Dynamics	$\partial_{\tau}x_i=$
Biochemical	$F -B x_i - R \sum_j A_{ij} x_i x_j$
Epidemics	$-B x_i + R \sum_j A_{ij} (1-x_i)x_j$
Mutualistic	$B x_i (1 - x_i) + R \sum_j A_{ij} x_i \frac{x_j^b}{1+x_j^b}$
Neuronal	$-B x_i + C \tanh x_i + R \sum_j A_{ij} \tanh x_j$
Noisy voter model	$A - B x_i + \frac{C}{k_i} \sum_j A_{ij} x_j$
Population	$-B x_i^{b} + R \sum_j A_{ij} x_j^a$
Regulatory	$-B x_i^a + R \sum_j A_{ij} \frac{x_j^h}{1+x_j^h}$
Synchronization	$\omega_i + R \sum_j A_{ij} \sin(x_j-x_i)$

---

Package Structure

├── LICENSE
├── pyproject.toml
├── README.md
├── src
│   ├── jacobian_geometry
│   │   ├── dynamics
│   │   │   ├── base.py
│   │   │   ├── biochemical.py
│   │   │   ├── diffusion_interaction.py
│   │   │   ├── epidemics.py
│   │   │   ├── __init__.py
│   │   │   ├── mutualistic.py
│   │   │   ├── neuronal.py
│   │   │   ├── noisyvm.py
│   │   │   ├── population.py
│   │   │   ├── regulatory2.py
│   │   │   ├── regulatory.py
│   │   │   ├── synchronization_norm.py
│   │   │   └── synchronization.py
│   │   ├── __init__.py
│   │   ├── metrics
│   │   │   ├── brockmann_barzel_distances.py
│   │   │   ├── distance.py
│   │   │   ├── __init__.py
│   │   │   └── statistics.py
│   │   └── utils
│   │       ├── __init__.py
│   │       ├── plotting.py
└── tests
    └── test.py

---

Top-Level API

You can import the most important tools directly from the top-level package:

import jacobian_geometry as jg

Dynamics and Integration

• jg.integrate_dynamics – Run simulations on a given network
• jg.compute_jacobian – Compute Jacobian at a state
• jg.jacobian_distance – Compute Jacobian distance

Possible Dynamics: ['Mutualistic', 'Biochemical', 'Population', 'Regulatory','Epidemics','Synchronization', 'Neuronal', 'NoisyVM', 'Diffusion']

Functional Distances

from jacobian_geometry.metrics import (
    compute_distance,
    average_distance,
    jacobian_distance,
    community_detection,
)

Also available:

from jacobian_geometry.metrics.brockmann_barzel import (
    Probability_Matrix,
    Brockmann_Distance_Matrix,
    Barzel_and_Brockmann_Distance,
    Barzel_and_Brockmann_Matrix,
)

Visualization

from jacobian_geometry.utils import plotting

---

License

MIT License.

---

Author

Giacomo Barzon (giacomo.barzon@unipd.it)