Analysis

The analytic suite reads the statistics of self-organised dynamics at three scales. These measures are the qualities — the dynamical signatures that underwrite a capacity; where a score indicates that a capacity is present, these help explain how. Every measure below carries its equation, a one-line reading, and a Source callout to its Julia implementation. All operate on channels recorded by the Recorder (off the compute hot path), so nothing here perturbs a run.

For a concrete, runnable end-to-end example that collects these measures at both scales from a single forage rollout — per-agent branching, node/agent susceptibility, correlation length, contact-graph clusters, and a crossshift_null control — see the two-scale data-collection harness:

Source: examples/forage_criticality.jl.

Criticality (node scale)

Branching ratio — the MR estimator

For a population-activity series $A(t)$, the branching ratio $m$ is how much activity one tick begets the next. The naive slope $\hat m = \sum A_t A_{t+1} / \sum A_t^2$ is biased under subsampling (Wilting & Priesemann 2018) — and this is subsampling (a scalar summary of the population). The multistep-regression estimator fixes it: for lags $k = 1\dots k_{\max}$ take the (intercept-corrected) slope $r_k$ of $A(t{+}k)$ on $A(t)$, then fit

$$r_k = b\,m^{k} \quad\Longrightarrow\quad \log r_k = \log b + k\log m,$$

and read $m$ off the exponential decay — which is invariant to the subsampling that distorts the single-lag slope.

Source: src/analysis/Branching.jl — branching_ratio (per-tick + legacy σ), branching_ratio_mr.

Caution

The Falandays homeostat regulates the population rate directly, so $m \approx 1$ can be rate-pinned rather than emergent — read it alongside the spectral radius (below).

Neuronal avalanches

Threshold $A(t)$ into supra-threshold excursions; each avalanche has a size $S$ (summed activity) and duration $D$. Near criticality both are power laws, $P(S)\sim S^{-\tau}$ and $P(D)\sim D^{-\alpha}$, tied by the crackling-noise scaling relation

$$\frac{\alpha-1}{\tau-1} \;=\; \gamma, \qquad \langle S\rangle(D)\sim D^{\gamma}.$$

Agreement of the three exponents is a far stronger criticality claim than any single $\sigma$ (Beggs & Plenz 2003).

Source: src/analysis/Avalanches.jl — avalanches (τ, α, γ_fit vs γ_pred).

Spectral radius

The dominant magnitude of the learned recurrent matrix, $\rho(W) = \max_i |\lambda_i(W)|$ — the linear-stability read that complements the branching (avalanche) read. Tracked over the rollout, and per agent.

Source: src/analysis/Spectral.jl.

Per-node distance-to-target

Each node has a homeostatic target $T_i$; its instantaneous strain is $|a_i - T_i|$. The across-node distribution is an “internal effort map” — which nodes are working, which are settled.

Source: src/analysis/TargetError.jl — node_target_error.

Cross-level — the same measure at two scales

The point of the whole programme: measure the same signature at the node scale and the agent scale, and ask where each sits relative to its own critical point — because information transmission is expected to peak near criticality, so locating the transition at each scale is the prerequisite for everything downstream. Every criticality estimator takes a level:

• :node — each agent’s own reservoir, as its per-agent population rate (fit per agent, then averaged — not node-to-node despite the name),
• :agent — the per-tick count of agents undergoing a turn event ($|\Delta\theta| > \theta_{\text{thr}}$, default $\pi/12$) — a genuine agent-scale cascade, not the pooled node rate rescaled,
• :pooled — all nodes of all agents in one series (the legacy default; it mixes distinct reservoirs, so read it as a population summary, not “the reservoir’s” dynamics).

Not every measure is comparable across levels — this matters, because plotting an incomparable pair against each other is a real inferential error. Susceptibility is the natural candidate pair: node ($\chi = N\,\mathrm{Var}[\text{synchrony}]$) and agent ($\chi = n\,\mathrm{Var}[\text{polarization}]$) are formally the same quantity. But a powered re-test refuted the apparent agent-scale signal against the circular-shift null, and branching fails it outright (agent-scale branching is dominated by within-agent maneuvers). So, stated honestly: no ensemble-scale criticality measure has yet survived the null as a validated cross-level quantity — agent-branching is a labelled negative control, and agent-susceptibility is not (yet) trustworthy either. Node-scale measures stand on their own; cross-level pairing remains an open, actively-nulled question. When a pair does survive, compare its peak positions as a control parameter is swept, not raw magnitudes (the prefactors $N\approx100$ vs $n\approx6$ differ by an order of magnitude).

Source: src/analysis/ActivityLevels.jl; consumed by Branching / Avalanches / SecondOrder.

Second-order signatures (both levels)

$$\chi = N\,\mathrm{Var}[\phi], \qquad F = \frac{\mathrm{Var}[A]}{\langle A\rangle}, \qquad \mathrm{PR} = \frac{(\sum_i \lambda_i)^2}{\sum_i \lambda_i^2}$$

Susceptibility $\chi$ (order parameter $\phi$ = synchrony at node scale, polarization at agent scale), the Fano factor $F$, and the participation ratio PR (effective dimensionality of the activity covariance). A criticality hypothesis predicts these peak together across levels as a control parameter is swept.

Source: src/analysis/SecondOrder.jl.

Null test — crossshift_null

Before a cross-scale coupling number is trusted, run it through the circular-shift null. Each surrogate independently circular-shifts every agent’s recorded time series, so each agent’s own dynamics are preserved while the inter-agent timing is destroyed. The measure is recomputed on the surrogate ensemble; comparing the real value against the null distribution separates genuine cross-agent coupling from what any independent set of single-agent series would produce by chance. Returns (real, null_mean, null_std, ratio) over n_shifts draws — a ratio near $1$ means the apparent coupling is indistinguishable from the null. Because the null strips both real coupling and common-source drive, read the coupling as the vision-on minus vision-off difference, not the raw ratio.

Source: src/analysis/NullTest.jl — crossshift_null.

Collective (agent scale)

These are descriptors (qualities), not competence scores — they measure how a swarm is organised, read alongside a task’s capacity-indicator, never as a competence measure in their own right (see Scoring).

• Polarization $\;P = \big|\frac{1}{N}\sum_i e^{i\theta_i}\big|$ — heading alignment, $0$ disordered → $1$ aligned.
• Milling — rotational order about the torus-aware circular centroid.
• Cohesion — mean nearest-neighbour + pairwise distance (periodic-boundary aware).
• Swarm regime — a discrete label (polarized, milling, swarming, or static) from $P$, milling, and speed.
• Correlation length — the distance at which the velocity-fluctuation correlation crosses zero (Cavagna et al. 2010 form: subtract the global mean velocity, normalize once globally).
• Contact-graph clusters — build the per-tick within-vision-radius contact graph and summarize its connected components: number of components, largest-component fraction, and mean component size (torus-aware). A graph-level readout of how the swarm fragments and coalesces (surfaced in sweeps as the contact_clusters measure).

Source: src/world/Metrics.jl (polarization, milling, cohesion) and src/analysis/SwarmAnalysis.jl (swarm_regime, correlation_length, contact_graph_clusters).

Read these at the swept sample size

Several estimators return a confident number rather than NaN when they are under-powered, so read them against the actual run size. At n_agents = 6 the correlation length, agent-scale susceptibility, and agent participation ratio are severely under-sampled (6 points, 15 pairs) — time-pooling over a long rollout hides the noise but does not remove it; treat them as uninterpretable below ~20–30 agents. Branching (MR) should be read with its per-agent distribution and fit quality, not the bare mean — a low-$R^2$ exponential fit still returns a finite $m$. Avalanche exponents need many events (tens to hundreds); a fit from a handful is meaningless. And any cross-agent claim should clear the circular-shift null (crossshift_null, NullTest.jl) before it is trusted — the null strips both real coupling and common-source drive, so the coupling readout is the vision-on minus vision-off difference.

Information flow

Transfer entropy — directional, order-1 discrete plug-in estimator:

$$\mathrm{TE}_{X\to Y} = \sum p(y_{t+1}, y_t, x_t)\,\log_2\frac{p(y_{t+1}\mid y_t, x_t)}{p(y_{t+1}\mid y_t)} .$$

Two variants: node-to-node within a reservoir (spike trains), and agent-to-agent (binarised heading change) — the direct measure for the social-foraging “do they use each other as a guide?” question. Experimental (plug-in bias; a KSG upgrade is flagged).

Source: src/analysis/TransferEntropy.jl — transfer_entropy, node_transfer_entropy, agent_transfer_entropy.

---

References

Beggs & Plenz (2003), J. Neurosci. · Wilting & Priesemann (2018), Nat. Commun. · Del Papa, Priesemann & Triesch (2017), PLOS ONE · Cavagna et al. (2010), PNAS.