braintools.analysis.population.avalanches

Contents

braintools.analysis.population.avalanches#

braintools.analysis.population.avalanches(counts, threshold=0, max_avalanches=None)#

Detect neuronal avalanches in a population count series.

An avalanche is a maximal run of consecutive bins in which the count exceeds threshold [1]. Its duration is the number of bins in the run and its size is the sum of counts - threshold over the run (the number of events for threshold=0). Runs that touch the start or the end of the series count as avalanches.

Parameters:

  • counts (Any) – Population event counts per time bin, shape (T,), for example SpikeTrains.bin(bin_size).sum(axis=1).

  • threshold (Any) – Activity threshold; bins with counts > threshold are active.

  • max_avalanches (int | None) – Static length of the padded outputs. Defaults to T // 2 + 1, which can hold every possible avalanche. When more avalanches occur, only the first max_avalanches are kept and n is clipped.

Returns:

Named tuple (sizes, durations, n). sizes and durations have shape (max_avalanches,) and are padded with zeros after the first n entries. sizes has the dtype of counts - threshold.

Return type:

AvalancheResult

Raises:

ValueError – If counts is not 1-D, or max_avalanches < 1.

See also

branching_ratio

Ratio of descendants to ancestors.

Notes

Runs are found without a loop over time: the run index of every active bin is a cumulative sum of run starts, and the sizes and durations are segment sums. Works under jax.jit and jax.vmap (for example over trials). The output shape depends only on T and max_avalanches.

References

Examples

>>> import jax.numpy as jnp
>>> from braintools.analysis.population import avalanches
>>> counts = jnp.array([2, 1, 0, 0, 3, 0, 1, 4, 2])
>>> res = avalanches(counts, max_avalanches=4)
>>> res.sizes, res.durations, res.n
(Array([3, 3, 7, 0], dtype=int32), Array([2, 1, 3, 0], dtype=int32), Array(3, dtype=int32))
>>>
>>> # Get the counts from a spike raster:
>>> from braintools.spike import SpikeTrains
>>> raster = jnp.zeros((10, 4)).at[jnp.array([1, 2, 6]), jnp.array([0, 3, 1])].set(1.)
>>> st = SpikeTrains.from_dense(raster, dt=1.)
>>> avalanches(st.bin(1.).sum(axis=1)).n
Array(2, dtype=int32)
Contents