spikegen 0.4.0

Generate spike trains (Poisson, gamma renewal, regular, Bernoulli, inhomogeneous) in pure Python with zero dependencies.

spikegen

Generate spike trains in pure Python with zero dependencies. Poisson, gamma renewal, regular, Bernoulli, and inhomogeneous processes, returned as plain sorted lists of spike times, with explicit seeds for reproducibility.

Install

pip install spikegen

30-second example

from spikegen import homogeneous_poisson, regular, gamma_renewal, with_refractory

homogeneous_poisson(rate=50.0, duration=2.0, seed=0)   # Poisson spikes in [0, 2)
regular(rate=10.0, duration=1.0)                        # [0.0, 0.1, 0.2, ...]
gamma_renewal(rate=20.0, shape=2.0, duration=1.0, seed=0)  # more regular than Poisson

spikes = homogeneous_poisson(rate=80.0, duration=1.0, seed=0)
with_refractory(spikes, refractory=0.002)              # enforce a 2 ms refractory period

from spikegen import population
population(lambda s: homogeneous_poisson(rate=50.0, duration=2.0, seed=s), units=10, seed=0)

from spikegen import bernoulli, jitter

# Discrete-time Bernoulli process: 1 ms bins, 50 Hz rate over 1 second
bernoulli(rate=50.0, duration=1.0, dt=0.001, seed=0)

# Jitter: add Gaussian noise (sigma=2 ms) to each spike time, useful for surrogate data
spikes = homogeneous_poisson(rate=40.0, duration=1.0, seed=0)
jitter(spikes, sigma=0.002, seed=1)

Times are in the same units as 1 / rate (seconds if rate is in Hz). Seeded processes are reproducible: the same seed gives the same train.

Optional NumPy fast path

The core package has zero runtime dependencies. For long, high-rate Poisson trains there is an optional vectorized generator behind the [fast] extra:

pip install spikegen[fast]

from spikegen import homogeneous_poisson_numpy

# Same homogeneous Poisson process as homogeneous_poisson, but vectorized with NumPy.
homogeneous_poisson_numpy(rate=1000.0, duration=10.0, seed=0)

homogeneous_poisson_numpy(rate, duration, seed) draws exponential inter-spike intervals in batches and takes their cumulative sum with NumPy instead of looping in Python, which is much faster for long, high-rate trains. NumPy is imported lazily only inside this function, so the pure-Python homogeneous_poisson stays the default and the package still imports with no dependencies; calling homogeneous_poisson_numpy without [fast] installed raises an ImportError.

The fast path is reproducible for a fixed seed but is not bit-identical to homogeneous_poisson for the same seed: it uses NumPy's Generator (PCG64), a different random stream from the pure path's random.Random (Mersenne Twister). The two are statistically equivalent: both produce a homogeneous Poisson process with the same rate, so their spike counts, mean rate, and inter-spike-interval distribution agree.

Why this exists

Generating synthetic spike trains is a daily need, but the generators live inside heavy frameworks: elephant requires neo and quantities, pyspike is NumPy-based, and other options are old or partial. spikegen is a small, dependency-free generator that returns plain lists of floats, so reproducible spike trains are one import away. It pairs with spikedist: generate trains, then measure the distance between them.

Processes

• regular(rate, duration): evenly spaced spikes. Deterministic.
• homogeneous_poisson(rate, duration, seed): constant-rate Poisson process.
• inhomogeneous_poisson(rate_fn, max_rate, duration, seed): time-varying rate by thinning.
• gamma_renewal(rate, shape, duration, seed): gamma inter-spike intervals; shape 1 is Poisson, larger shape is more regular.
• bernoulli(rate, duration, dt, seed): discrete-time Bernoulli process. Time is divided into bins of width dt; each bin fires at its start time with probability rate * dt. Raises ValueError when rate * dt > 1.
• with_refractory(times, refractory): drop spikes within a minimum interval.
• jitter(times, sigma, seed): add independent Gaussian jitter (standard deviation sigma) to each spike time and return sorted results. Useful for surrogate or null datasets that destroy precise timing while preserving spike count. sigma = 0 sorts without change.
• population(make, units, seed): build a population of trains by calling make(seed) once per unit with independent, reproducible child seeds derived from the base seed.

All parameters after the first are keyword-only and explicit.

Testing

pip install -e ".[dev]"
pytest

Tests cover exact values for the deterministic generators, seeded reproducibility, the rate-bound and ordering invariants, and the validation paths, with property tests via Hypothesis.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

License

MIT. See LICENSE.