Skip to content
BrainlessLab BrainlessLab BrainlessLab

Analysis reference

An analysis describes recorded behaviour or dynamics. It does not establish capacity or a mechanism by itself. Read each analysis beside the task outcome, sampling protocol, diagnostics, and a control that matches the claim.

ProfilePlan is the standard way to request registered analyses. The executor records the channels they require and reports analysis failures explicitly. The default Falandays profile contains node_target_error, spectral_radius, and fano_factor. Experimental analyses remain registered and requestable by name, but a default profile does not run them.

Specify the method before the run

For each confirmatory analysis, declare:

  • the input channels and sampling interval;
  • transient removal and analysis window;
  • threshold, bin, lag, or neighbourhood settings;
  • treatment of failed, dead, missing, and saturated runs;
  • the independent unit and uncertainty method;
  • estimator diagnostics and minimum data;
  • null or surrogate procedure;
  • multiplicity correction when several measures, lags, or pairs are tested.

Bootstrap the independent run or randomised block. Agents and ticks inside one world are not additional independent replicates.

Task and node diagnostics

Task metrics measure the implemented outcome and its descriptors. Node diagnostics help explain how a run developed.

node_target_error measures each node’s distance from its local target:

di(t)=∣ai(t)−Ti(t)∣.d_i(t) = |a_i(t)-T_i(t)|.

Report its distribution or a declared summary. A small value means the modelled activation is near its target. It does not prove biological homeostasis or useful behaviour.

Source: src/analysis/TargetError.jl.

fano_factor also returns the mean and variance of the recorded node activity rate. Its Fano field is the variance-to-mean ratio of the corresponding spike-count series. Read branching and other dynamics measures beside this rate summary. Silent activity returns zero for all three values.

Source: src/analysis/SecondOrder.jl.

Branching estimates

For population activity A(t)A(t), a one-step branching estimate asks how strongly activity predicts the next sample. A simple regression can be biased when the observed series is a subsampled or noisy projection.

The multistep-regression estimator fits regression slopes across lags:

rk=b mk,log⁡rk=log⁡b+klog⁡m.r_k = b\,m^k, \qquad \log r_k = \log b + k\log m.

The fitted decay gives the branching estimate mm under the estimator’s assumptions. Read it with the accepted lags, fit quality, sample count, and per-agent distribution. A value near one is not sufficient evidence of criticality.

The current experimental implementation reads a synthetic process with true m=0.50m=0.50 as 0.8160.816. Its only ground-truth regression test uses m=0.90m=0.90, where this bias is not visible. Treat the estimate as biased until a suitable calibration shows otherwise.

The Falandays rule directly regulates activity. This feedback can hold an activity statistic near a target. Compare branching estimates with controls and other diagnostics before assigning a critical interpretation.

Source: src/analysis/Branching.jl — branching_ratio, branching_ratio_mr.

Avalanches

The avalanche analysis thresholds population activity into contiguous events. It reports each event’s size and duration, onset-to-onset intervals, their mean, the event count, and the threshold used. The default threshold adapts to the recorded activity.

This analysis is descriptive only. Current runs provide too few events for supported distributional fits and show large seed-to-seed count changes at a fixed condition. Do not use this output to compare conditions or infer criticality.

Source: src/analysis/Avalanches.jl.

Spectral radius

For recurrent weight matrix WW, the spectral radius is:

ρ(W)=max⁡i∣λi(W)∣.\rho(W)=\max_i|\lambda_i(W)|.

It is a linear matrix diagnostic. A threshold-reset, plastic spiking system is nonlinear, so spectral radius is not a general stability criterion. Use it to describe the recurrent matrix and compare declared conditions.

Source: src/analysis/Spectral.jl.

Second-order measures

The analysis suite includes susceptibility, Fano factor, and participation ratio:

χ=N Var[ϕ],F=Var[A]⟨A⟩,PR=(∑iλi)2∑iλi2.\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}.

At node scale, the order parameter can describe neural synchrony. At agent scale, it can describe collective order such as polarisation. Similar equations do not make the two levels numerically commensurate. Compare their locations across a declared control sweep, not their raw magnitudes.

Susceptibility and participation ratio remain experimental. Independent Bernoulli activity gives susceptibility a rate floor of p(1−p)p(1-p). Two zero-correlation reservoirs with 10% and 30% activity therefore differ by about 2.4 times from rate alone. Match activity rates before comparing this measure.

Participation ratio needs enough recorded ticks as well as enough simultaneously observed units. Its covariance rank, and therefore its reported value, cannot exceed n_ticks - 1. The implementation rejects a series with fewer recorded ticks than units because this ceiling would otherwise dominate silently. The activity-rate summary remains a core descriptive diagnostic.

Source: src/analysis/ActivityLevels.jl, src/analysis/SecondOrder.jl.

Collective measures

Collective analyses describe organisation among agents:

  • polarisation measures heading alignment;
  • milling measures rotational order around a torus-aware centre;
  • cohesion summarises nearest-neighbour and pairwise distance;
  • swarm_regime assigns a descriptive state from order and speed;
  • correlation_length finds the zero crossing of velocity-fluctuation correlation;
  • contact_graph_clusters summarises connected components in a proximity graph.

These values are descriptors, not task scores. A highly aligned group may still fail its task. Use torus-aware geometry when the world is periodic, and retain independent worlds as the uncertainty unit.

Source: src/world/Metrics.jl, src/analysis/SwarmAnalysis.jl.

Transfer entropy

The current transfer-entropy estimator is a directional, order-one, discretised plug-in estimate:

TEX→Y=∑p(yt+1,yt,xt)log⁡2p(yt+1∣yt,xt)p(yt+1∣yt).\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)}.

The suite can apply it to node spike trains or agent movement events. The estimate can be biased upwards with finite samples. On independent data at N=500 and bins=8, it reports 0.674 bits: 22% of the 3-bit dynamic range. Check stationarity, binning sensitivity, sample count, time-shift surrogates, and correction across tested pairs.

Transfer entropy shows predictive information under the estimator. It does not by itself show direct causal influence.

Source: src/analysis/TransferEntropy.jl.

Circular-shift null

crossshift_null independently circularly shifts each agent’s recorded series. This keeps each series’ internal dynamics while disrupting their alignment across agents.

The result includes the observed value, null values, null mean and standard deviation, ratio, Monte Carlo p-value, requested surrogate count, and valid surrogate count. The ratio is descriptive. A value near one does not establish equivalence or absence of coupling.

Circular shifts also disrupt timing caused by shared inputs. Pair this surrogate with a causal condition suited to the question, such as an input-disabled or sham-input control.

Source: src/analysis/NullTest.jl.

Registered analysis workflow

Inspect analyses that can apply to a task:

analyses(DEFAULT_REGISTRY; task=:tracking)

Then add their keys to a profile plan:

[profile]
target = "tracking"
analyses = ["branching_ratio_mr", "node_target_error"]
record_every = 1

If an analysis needs a missing channel or cannot process a trial, the profile result retains an explicit error. Do not replace a failed analysis with a silent zero or omit the run.

Primary references