Metadata-Version: 2.4
Name: spikegen
Version: 0.3.0
Summary: Generate spike trains (Poisson, gamma renewal, regular, Bernoulli, inhomogeneous) in pure Python with zero dependencies.
Project-URL: Homepage, https://github.com/amaar-mc/spikegen
Project-URL: Repository, https://github.com/amaar-mc/spikegen
Project-URL: Issues, https://github.com/amaar-mc/spikegen/issues
Project-URL: Changelog, https://github.com/amaar-mc/spikegen/blob/main/CHANGELOG.md
Author: Amaar Chughtai
License: MIT License
        
        Copyright (c) 2026 Amaar Chughtai
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: computational-neuroscience,neuromorphic,neuroscience,point-process,poisson-process,renewal-process,simulation,spike-train,spiking-neural-networks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# spikegen

<p align="center">
  <img src="assets/logo.png" alt="spikegen logo" width="160">
</p>

[![PyPI](https://img.shields.io/pypi/v/spikegen)](https://pypi.org/project/spikegen/)
[![CI](https://github.com/amaar-mc/spikegen/actions/workflows/ci.yml/badge.svg)](https://github.com/amaar-mc/spikegen/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

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

```sh
pip install spikegen
```

## 30-second example

```python
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.

## 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](https://pypi.org/project/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

```sh
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](./CONTRIBUTING.md).

## License

MIT. See [LICENSE](./LICENSE).
