spikestats 0.2.0__tar.gz

spikestats-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: A wrong or surprising statistic
+title: ""
+labels: bug
+---
+
+## Call
+
+The metric and parameters, including the spike times, for example
+`cv_isi([0.0, 0.1, 0.3, 0.6])` or `fano_factor(spikes, duration=2, bin_width=0.1)`.
+
+## Expected
+
+The value you expected, and the definition or source it follows.
+
+## Actual
+
+What you observed.
+
+## Environment
+
+- spikestats version:
+- Python version:

spikestats-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest a metric or capability for spikestats
+title: ""
+labels: enhancement
+---
+
+## What
+
+The metric or capability you would like.
+
+## Why
+
+The workflow this would support.
+
+## References
+
+The definition or paper that pins down the expected behavior.

spikestats-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## Summary
+
+What this changes and why.
+
+## Checklist
+
+- [ ] Tests added or updated (a bug fix starts with a failing test)
+- [ ] Exact-value test and any known limit (regular train, Poisson) covered for a new metric
+- [ ] `uv run ruff check .` passes
+- [ ] `uv run mypy src` passes
+- [ ] `uv run pytest` passes
+- [ ] No runtime dependencies added
+- [ ] No em dash characters in docs or commit messages

spikestats-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest -q

spikestats-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+uv.lock
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+.DS_Store

spikestats-0.2.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0]
+
+### Added
+
+- `binned_spike_counts(spikes, *, duration, bin_width) -> list[int]`: spike counts in
+  `int(duration / bin_width)` consecutive non-overlapping bins tiling `[0, duration)`.
+- `time_resolved_rate(spikes, *, duration, bin_width, step) -> tuple[list[float], list[float]]`:
+  sliding-window firing rate. Returns `(window_center_times, rates_in_hz)`. Window positions use
+  integer indexing of `step` to avoid floating-point drift. The last window included is the
+  largest k where `k * step + bin_width <= duration`.
+- `psth(trials, *, duration, bin_width) -> tuple[list[float], list[float]]`: peristimulus time
+  histogram over multiple trials. Returns `(bin_center_times, mean_rate_per_bin_hz)` averaged
+  over all trials. Raises `ValueError` on empty `trials`.
+- `time_resolved_fano(trials, *, duration, bin_width) -> tuple[list[float], list[float]]`:
+  per-bin Fano factor (population variance / mean of per-trial counts) across trials. Returns
+  `(bin_center_times, fano_per_bin)`. Bins where the mean count across all trials is 0 are
+  returned as `float('nan')`.
+
+### Design notes
+
+- Boundary policy: all time-resolved functions use `[0, duration)` -- a spike at exactly
+  `duration` is excluded, matching the existing `spike_counts` convention.
+- Variance choice: `time_resolved_fano` uses population variance (denominator N), matching
+  `fano_factor` in metrics.py. With one trial, pvariance of a single sample is 0, so all
+  non-empty bins return 0. Callers who need sample variance should use multiple trials.
+- Zero-mean bins in `time_resolved_fano`: returned as `float('nan')` so callers can identify
+  and exclude them.
+
+### Not included in this release
+
+- PyPI publish is queued behind the new-project-creation quota (currently returning 429 for new
+  packages). The sdist and wheel are twine-verified in `dist/`; upload will proceed once the
+  quota resets.
+
+## [0.1.0]
+
+### Added
+- `firing_rate(spikes, *, duration)`: mean firing rate.
+- `inter_spike_intervals(spikes)`: consecutive interval list.
+- `cv_isi(spikes)`: coefficient of variation of the inter-spike intervals.
+- `cv2(spikes)`: local CV2 averaged over adjacent interval pairs (Holt et al. 1996).
+- `lv(spikes)`: local variation (Shinomoto et al. 2003).
+- `lvr(spikes, *, refractory)`: revised local variation LvR (Shinomoto et al. 2009).
+- `spike_counts(spikes, *, duration, bin_width)`: counts per equal-width bin.
+- `fano_factor(spikes, *, duration, bin_width)`: Fano factor of binned counts.
+- Pure Python, zero runtime dependencies. Inputs are plain lists of spike times, matching
+  spikegen and spikedist.
+- Test suite: exact-value tests, known-limit tests (regular train 0, Poisson 1), and
+  property-based invariants.

spikestats-0.2.0/CLAUDE.md

@@ -0,0 +1,49 @@
+# spikestats
+
+Pure-Python spike-train statistics. Zero runtime dependencies. Completes the toolkit with
+spikegen (generate) and spikedist (compare).
+
+## Commands
+
+- Create env and install: `uv venv && uv pip install -e ".[dev]"`
+- Test: `uv run pytest -q`
+- Lint: `uv run ruff check .` (format with `uv run ruff format .`)
+- Types: `uv run mypy src`
+- Build: `uv build` (then `uv run --with twine twine check dist/*` before publishing)
+- Example: `python examples/summary.py`
+
+## Architecture
+
+`src/spikestats/`:
+- `_validate.py` shared validation (positivity, non-negativity, finite times, minimum spikes)
+- `metrics.py` the statistics (firing_rate, inter_spike_intervals, cv_isi, cv2, lv, lvr,
+  spike_counts, fano_factor)
+- `__init__.py` public surface
+
+See `docs/architecture.md` for the formulas and references.
+
+## Conventions
+
+- A spike train is a plain `list[float]` of times; functions sort the input internally.
+- Metrics return plain `float`; intervals and counts return lists.
+- Parameters after `*` are keyword-only; no default values.
+- No runtime dependencies (standard library `statistics` and `math` only). Note the module
+  is `metrics.py`, not `statistics.py`, to avoid shadowing the standard library module.
+
+## Testing rules
+
+- Exact value for every metric against a hand-computed example.
+- Known limits: a regular train gives 0, a Poisson process gives 1 (CV, Lv, Fano).
+- The identity LvR(refractory=0) == Lv is asserted.
+- Hypothesis property tests for bounds and invariants; bug fixes start with a failing test.
+
+## Release
+
+- Semantic versioning; update `CHANGELOG.md` and `__version__`.
+- Gates: `uv run pytest && uv run ruff check . && uv run mypy src && uv build && uv run twine check dist/*`.
+- Publish to PyPI, tag `vX.Y.Z`, GitHub release.
+
+## Style
+
+- No em dash characters in docs, comments, or commit messages.
+- Comments explain non-obvious reasoning only.

spikestats-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Showing empathy and kindness toward other people.
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Focusing on what is best for the community.
+
+Examples of unacceptable behavior:
+
+- Harassment, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information without explicit permission.
+- Other conduct which could reasonably be considered inappropriate.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainer at amaar2cool@gmail.com. All complaints will be
+reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

spikestats-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to spikestats
+
+Thanks for your interest. This project values correctness, clear references, and zero
+runtime dependencies.
+
+## Development
+
+```sh
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+```
+
+A standard virtual environment with `pip install -e ".[dev]"` works the same way.
+
+## Guidelines
+
+- No runtime dependencies. The standard library `statistics` and `math` are enough.
+- Every metric needs an exact-value test against a hand-computed example and, where it
+  applies, a known limit (a regular train is 0, a Poisson process is 1).
+- New metrics must cite the definition they implement in the docstring and in
+  docs/architecture.md, so the formula can be checked against a source.
+- Parameters after `*` are keyword-only with no default values.
+- A bug fix starts with a failing test.
+- Run `uv run ruff format .` before committing.
+- Commit messages follow `type(scope): description`.
+
+## Reporting issues
+
+Open an issue with the spike times, the call and its parameters, and the value you expected
+versus the value you observed.

spikestats-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+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.

spikestats-0.2.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: spikestats
+Version: 0.2.0
+Summary: Spike-train statistics (firing rate, CV, CV2, Fano factor, local variation Lv and LvR, PSTH, time-resolved rate and Fano) in pure Python with zero dependencies.
+Project-URL: Homepage, https://github.com/amaar-mc/spikestats
+Project-URL: Repository, https://github.com/amaar-mc/spikestats
+Project-URL: Issues, https://github.com/amaar-mc/spikestats/issues
+Project-URL: Changelog, https://github.com/amaar-mc/spikestats/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: coefficient-of-variation,computational-neuroscience,fano-factor,firing-rate,local-variation,neuromorphic,neuroscience,point-process,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
+
+# spikestats
+
+<p align="center">
+  <img src="assets/logo.png" alt="spikestats logo" width="160">
+</p>
+
+Spike-train statistics in pure Python, with zero dependencies.
+
+`spikestats` computes the standard measures of spike-train rate and variability from a plain
+list of spike times: firing rate, inter-spike intervals, coefficient of variation, CV2,
+local variation (Lv and the refractory-corrected LvR), spike counts, and the Fano factor.
+There is nothing to configure and nothing to install beyond the package itself: the input
+is a `list[float]` of spike times and the output is a `float`.
+
+It pairs with [spikegen](https://github.com/amaar-mc/spikegen) for generating trains and
+[spikedist](https://github.com/amaar-mc/spikedist) for comparing them. The three share the
+same plain-list data model, so they compose without adapters.
+
+## Why
+
+The established tools for these measures, Elephant and spiketools, are excellent but pull in
+NumPy, SciPy, and custom data objects (`neo.SpikeTrain` and friends). When you only need a
+firing rate or a CV from a list of spike times, that is a heavy dependency tree to carry, and
+it is awkward in teaching material, small scripts, and lightweight pipelines. `spikestats`
+keeps the math, drops the dependencies, and works on the lists you already have.
+
+## Install
+
+```sh
+pip install spikestats
+```
+
+## Usage
+
+```python
+import spikestats as ss
+
+spikes = [0.012, 0.031, 0.058, 0.090, 0.110, 0.155]  # seconds
+
+ss.firing_rate(spikes, duration=0.2)   # spikes per second
+ss.inter_spike_intervals(spikes)       # consecutive differences
+ss.cv_isi(spikes)                      # coefficient of variation of the ISIs
+ss.cv2(spikes)                         # Holt et al. 1996, robust to rate drift
+ss.lv(spikes)                          # Shinomoto et al. 2003 local variation
+ss.lvr(spikes, refractory=0.002)       # Shinomoto et al. 2009, refractory-corrected
+ss.spike_counts(spikes, duration=0.2, bin_width=0.05)
+ss.fano_factor(spikes, duration=0.2, bin_width=0.05)
+```
+
+### Time-resolved metrics
+
+```python
+import spikestats as ss
+
+spikes = [0.012, 0.031, 0.058, 0.090, 0.110, 0.155, 0.210, 0.245]  # seconds
+
+# Non-overlapping bin counts tiling [0, duration)
+counts = ss.binned_spike_counts(spikes, duration=0.3, bin_width=0.1)
+# => [3, 3, 2]  (one list[int] per bin)
+
+# Sliding-window firing rate: returns (center_times, rates_hz)
+centers, rates = ss.time_resolved_rate(spikes, duration=0.3, bin_width=0.1, step=0.05)
+
+# PSTH averaged over multiple trials: returns (bin_center_times, mean_rate_hz)
+trials = [spikes, [0.020, 0.060, 0.100, 0.140, 0.200]]
+bin_centers, mean_rates = ss.psth(trials, duration=0.3, bin_width=0.1)
+
+# Per-bin Fano factor across trials: returns (bin_center_times, fano_per_bin)
+bin_centers, fano = ss.time_resolved_fano(trials, duration=0.3, bin_width=0.1)
+```
+
+## API
+
+All functions take spike times as a sequence of numbers and sort them internally.
+
+### Scalar metrics
+
+- `firing_rate(spikes, *, duration)`: spike count divided by `duration`.
+- `inter_spike_intervals(spikes)`: list of consecutive differences (empty for fewer than two spikes).
+- `cv_isi(spikes)`: population standard deviation of the ISIs over their mean. Regular train 0, Poisson 1.
+- `cv2(spikes)`: mean of `2 * |I(n+1) - I(n)| / (I(n+1) + I(n))` over adjacent intervals.
+- `lv(spikes)`: mean of `3 * ((I(n) - I(n+1)) / (I(n) + I(n+1)))^2`. Regular train 0, Poisson 1.
+- `lvr(spikes, *, refractory)`: LvR with a refractoriness constant in the spike-time unit.
+- `spike_counts(spikes, *, duration, bin_width)`: counts per equal-width bin tiling `[0, n * bin_width)`.
+- `fano_factor(spikes, *, duration, bin_width)`: population variance of the bin counts over their mean.
+
+### Time-resolved metrics
+
+All functions use the half-open boundary `[0, duration)`: a spike at exactly `duration` is excluded.
+
+- `binned_spike_counts(spikes, *, duration, bin_width) -> list[int]`: spike counts in
+  `int(duration / bin_width)` consecutive non-overlapping bins tiling `[0, duration)`.
+- `time_resolved_rate(spikes, *, duration, bin_width, step) -> tuple[list[float], list[float]]`:
+  sliding-window firing rate. Window of width `bin_width` steps by `step` across `[0, duration)`.
+  Returns `(window_center_times, rates_in_hz)`. Window positions are computed by integer indexing
+  of the step size to avoid floating-point drift.
+- `psth(trials, *, duration, bin_width) -> tuple[list[float], list[float]]`: peristimulus time
+  histogram. `trials` is a sequence of spike-time sequences. Returns `(bin_center_times,
+  mean_rate_per_bin_hz)` averaged over trials. Raises `ValueError` on empty `trials`.
+- `time_resolved_fano(trials, *, duration, bin_width) -> tuple[list[float], list[float]]`:
+  per-bin Fano factor (population variance / mean of per-trial counts). Returns
+  `(bin_center_times, fano_per_bin)`. Bins with zero mean across all trials are returned as
+  `float('nan')`. Uses population variance (denominator N), so a single trial always gives 0.
+
+Parameters after `*` are keyword-only and have no default values; pass them explicitly.
+
+## Notes
+
+- `cv_isi` uses the population standard deviation, matching the common `numpy.std` default.
+- `cv2`, `lv`, and `lvr` need at least three spikes; they raise a clear `ValueError` otherwise.
+- `spike_counts` uses `floor(duration / bin_width)` equal-width bins, so every bin has the same
+  width; any remainder of the duration and any spikes outside the binned window are ignored.
+- `binned_spike_counts` uses `int(duration / bin_width)` bins (same count). All time-resolved
+  functions use the half-open interval `[0, duration)`: a spike at `t == duration` is excluded.
+- `time_resolved_fano` uses population variance (denominator N). With a single trial, variance
+  is 0 for every bin; use multiple trials to get meaningful Fano estimates. Bins where the
+  mean count is 0 across all trials are returned as `float('nan')`.
+- PyPI publish is queued behind the new-project-creation quota (currently returning 429 for new
+  packages). The dist is twine-verified and ready; upload will proceed once the quota resets.
+
+## License
+
+MIT

spikestats-0.2.0/README.md

@@ -0,0 +1,123 @@
+# spikestats
+
+<p align="center">
+  <img src="assets/logo.png" alt="spikestats logo" width="160">
+</p>
+
+Spike-train statistics in pure Python, with zero dependencies.
+
+`spikestats` computes the standard measures of spike-train rate and variability from a plain
+list of spike times: firing rate, inter-spike intervals, coefficient of variation, CV2,
+local variation (Lv and the refractory-corrected LvR), spike counts, and the Fano factor.
+There is nothing to configure and nothing to install beyond the package itself: the input
+is a `list[float]` of spike times and the output is a `float`.
+
+It pairs with [spikegen](https://github.com/amaar-mc/spikegen) for generating trains and
+[spikedist](https://github.com/amaar-mc/spikedist) for comparing them. The three share the
+same plain-list data model, so they compose without adapters.
+
+## Why
+
+The established tools for these measures, Elephant and spiketools, are excellent but pull in
+NumPy, SciPy, and custom data objects (`neo.SpikeTrain` and friends). When you only need a
+firing rate or a CV from a list of spike times, that is a heavy dependency tree to carry, and
+it is awkward in teaching material, small scripts, and lightweight pipelines. `spikestats`
+keeps the math, drops the dependencies, and works on the lists you already have.
+
+## Install
+
+```sh
+pip install spikestats
+```
+
+## Usage
+
+```python
+import spikestats as ss
+
+spikes = [0.012, 0.031, 0.058, 0.090, 0.110, 0.155]  # seconds
+
+ss.firing_rate(spikes, duration=0.2)   # spikes per second
+ss.inter_spike_intervals(spikes)       # consecutive differences
+ss.cv_isi(spikes)                      # coefficient of variation of the ISIs
+ss.cv2(spikes)                         # Holt et al. 1996, robust to rate drift
+ss.lv(spikes)                          # Shinomoto et al. 2003 local variation
+ss.lvr(spikes, refractory=0.002)       # Shinomoto et al. 2009, refractory-corrected
+ss.spike_counts(spikes, duration=0.2, bin_width=0.05)
+ss.fano_factor(spikes, duration=0.2, bin_width=0.05)
+```
+
+### Time-resolved metrics
+
+```python
+import spikestats as ss
+
+spikes = [0.012, 0.031, 0.058, 0.090, 0.110, 0.155, 0.210, 0.245]  # seconds
+
+# Non-overlapping bin counts tiling [0, duration)
+counts = ss.binned_spike_counts(spikes, duration=0.3, bin_width=0.1)
+# => [3, 3, 2]  (one list[int] per bin)
+
+# Sliding-window firing rate: returns (center_times, rates_hz)
+centers, rates = ss.time_resolved_rate(spikes, duration=0.3, bin_width=0.1, step=0.05)
+
+# PSTH averaged over multiple trials: returns (bin_center_times, mean_rate_hz)
+trials = [spikes, [0.020, 0.060, 0.100, 0.140, 0.200]]
+bin_centers, mean_rates = ss.psth(trials, duration=0.3, bin_width=0.1)
+
+# Per-bin Fano factor across trials: returns (bin_center_times, fano_per_bin)
+bin_centers, fano = ss.time_resolved_fano(trials, duration=0.3, bin_width=0.1)
+```
+
+## API
+
+All functions take spike times as a sequence of numbers and sort them internally.
+
+### Scalar metrics
+
+- `firing_rate(spikes, *, duration)`: spike count divided by `duration`.
+- `inter_spike_intervals(spikes)`: list of consecutive differences (empty for fewer than two spikes).
+- `cv_isi(spikes)`: population standard deviation of the ISIs over their mean. Regular train 0, Poisson 1.
+- `cv2(spikes)`: mean of `2 * |I(n+1) - I(n)| / (I(n+1) + I(n))` over adjacent intervals.
+- `lv(spikes)`: mean of `3 * ((I(n) - I(n+1)) / (I(n) + I(n+1)))^2`. Regular train 0, Poisson 1.
+- `lvr(spikes, *, refractory)`: LvR with a refractoriness constant in the spike-time unit.
+- `spike_counts(spikes, *, duration, bin_width)`: counts per equal-width bin tiling `[0, n * bin_width)`.
+- `fano_factor(spikes, *, duration, bin_width)`: population variance of the bin counts over their mean.
+
+### Time-resolved metrics
+
+All functions use the half-open boundary `[0, duration)`: a spike at exactly `duration` is excluded.
+
+- `binned_spike_counts(spikes, *, duration, bin_width) -> list[int]`: spike counts in
+  `int(duration / bin_width)` consecutive non-overlapping bins tiling `[0, duration)`.
+- `time_resolved_rate(spikes, *, duration, bin_width, step) -> tuple[list[float], list[float]]`:
+  sliding-window firing rate. Window of width `bin_width` steps by `step` across `[0, duration)`.
+  Returns `(window_center_times, rates_in_hz)`. Window positions are computed by integer indexing
+  of the step size to avoid floating-point drift.
+- `psth(trials, *, duration, bin_width) -> tuple[list[float], list[float]]`: peristimulus time
+  histogram. `trials` is a sequence of spike-time sequences. Returns `(bin_center_times,
+  mean_rate_per_bin_hz)` averaged over trials. Raises `ValueError` on empty `trials`.
+- `time_resolved_fano(trials, *, duration, bin_width) -> tuple[list[float], list[float]]`:
+  per-bin Fano factor (population variance / mean of per-trial counts). Returns
+  `(bin_center_times, fano_per_bin)`. Bins with zero mean across all trials are returned as
+  `float('nan')`. Uses population variance (denominator N), so a single trial always gives 0.
+
+Parameters after `*` are keyword-only and have no default values; pass them explicitly.
+
+## Notes
+
+- `cv_isi` uses the population standard deviation, matching the common `numpy.std` default.
+- `cv2`, `lv`, and `lvr` need at least three spikes; they raise a clear `ValueError` otherwise.
+- `spike_counts` uses `floor(duration / bin_width)` equal-width bins, so every bin has the same
+  width; any remainder of the duration and any spikes outside the binned window are ignored.
+- `binned_spike_counts` uses `int(duration / bin_width)` bins (same count). All time-resolved
+  functions use the half-open interval `[0, duration)`: a spike at `t == duration` is excluded.
+- `time_resolved_fano` uses population variance (denominator N). With a single trial, variance
+  is 0 for every bin; use multiple trials to get meaningful Fano estimates. Bins where the
+  mean count is 0 across all trials are returned as `float('nan')`.
+- PyPI publish is queued behind the new-project-creation quota (currently returning 429 for new
+  packages). The dist is twine-verified and ready; upload will proceed once the quota resets.
+
+## License
+
+MIT

spikestats-0.2.0/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Scope
+
+`spikestats` is a pure computation library with no runtime dependencies, no network access,
+and no file system access. The attack surface is limited to incorrect results from
+malformed input, which the library guards against with explicit validation.
+
+## Reporting a vulnerability
+
+If you find a security issue, please email amaar2cool@gmail.com with details and steps to
+reproduce. Please do not open a public issue for security reports. You can expect an
+initial response within a few days.
+
+## Supported versions
+
+The latest published minor version receives fixes. Pre-1.0 releases may introduce breaking
+changes in minor versions, as allowed by semantic versioning.