Initial release: bin width estimation, all major methods

Includes: auto, freedman_diaconis, scott, sturges, rice, sqrt, doane,
stone, knuth, gcd_interval, bayesian_blocks, bin()

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: rickhonda

.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+dist/
+*.egg-info/
+.pytest_cache/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shun Richard Honda
+
+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.

README.md

@@ -0,0 +1,94 @@
+# binjamin
+
+**Bin width estimation — every major method in one place.**
+
+```python
+import binjamin as bj
+
+# Estimate bin width
+bj.auto(intervals)               # good default — max(FD, Sturges)
+bj.freedman_diaconis(intervals)  # robust, no distributional assumption
+
+# Bin data and get the artifact
+edges, counts = bj.bin(data)
+edges, counts = bj.bin(data, method='bayesian_blocks')
+```
+
+## Install
+
+```bash
+pip install binjamin
+```
+
+## Methods
+
+### Scalar — return a single bin width
+
+| Method | Formula | When to use |
+|---|---|---|
+| `auto` | max(FD, Sturges) | Good general default |
+| `freedman_diaconis` | 2·IQR·n^(-1/3) | Unknown or skewed distribution, outliers present |
+| `scott` | 3.5·σ·n^(-1/3) | Near-normal data, few outliers |
+| `sturges` | (max−min)/(1+log₂n) | Small, near-normal datasets |
+| `rice` | (max−min)/(2·n^(1/3)) | No assumption, simple alternative to FD |
+| `sqrt` | (max−min)/√n | Quick exploratory work |
+| `doane` | Sturges + skewness correction | Skewed or multimodal distributions |
+| `stone` | Cross-validation | Unknown distribution, accuracy over speed |
+| `knuth` | Maximum likelihood | Uniform bins, optimal posterior |
+| `gcd_interval` | GCD of intervals | Integer sequences, regularly-sampled data |
+
+### Variable-width — returns bin edges
+
+| Method | When to use |
+|---|---|
+| `bayesian_blocks` | Non-stationary event data; density varies across the domain |
+
+### Binning artifact
+
+| Function | Returns |
+|---|---|
+| `bin(data, method='auto')` | `(edges, counts)` — edges and observation counts per bin |
+
+## Usage
+
+All scalar methods take a 1-D array-like and return a `float`:
+
+```python
+import numpy as np
+import binjamin as bj
+
+intervals = np.diff(np.sort(event_times))  # inter-event intervals
+
+bj.freedman_diaconis(intervals)  # → float
+bj.scott(intervals)              # → float
+bj.knuth(intervals)              # → float
+```
+
+`bayesian_blocks` takes event positions (not intervals) and returns edges:
+
+```python
+edges = bj.bayesian_blocks(event_times, p0=0.05)
+# edges: array of variable-width bin boundaries
+# p0: false-positive rate for new change points (lower = fewer blocks)
+```
+
+`gcd_interval` takes integer-valued positions:
+
+```python
+bj.gcd_interval([0, 60, 120, 180, 300])  # → 60.0
+```
+
+## Choosing a method
+
+**Start with `auto`.** If the result looks wrong:
+
+- Heavy tails or outliers → `freedman_diaconis`
+- Known near-normal distribution → `scott`
+- Skewed data → `doane`
+- Event rate changes over time → `bayesian_blocks`
+- Integer sequence with known regular spacing → `gcd_interval`
+- Need provably optimal bins, willing to wait → `knuth` or `stone`
+
+## License
+
+[MIT](LICENSE)

pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "binjamin"
+version = "0.1.0"
+description = "Bin width estimation — all major methods in one place"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Shun Richard Honda", email = "shun.honda@adelic.org" }
+]
+keywords = ["binning", "histogram", "bin-width", "freedman-diaconis", "bayesian-blocks"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/adelic-ai/binjamin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/binjamin"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "twine>=6.2.0",
+]

src/binjamin/__init__.py

@@ -0,0 +1,61 @@
+"""
+binjamin — bin width estimation
+
+All major methods in one place. Every function takes a 1-D array of values
+(or inter-event intervals) and returns a scalar bin width estimate.
+
+Suggested import:
+
+    import binjamin as bj
+
+    bj.auto(intervals)
+    bj.freedman_diaconis(intervals)
+    bj.bayesian_blocks(orders)
+
+Methods returning a scalar bin width
+-------------------------------------
+    auto                — max(freedman_diaconis, sturges); numpy default
+    freedman_diaconis   — 2·IQR·n^(-1/3); robust, no distributional assumption
+    scott               — 3.5·σ·n^(-1/3); assumes normality
+    sturges             — (max-min)/(1+log₂n); assumes normality, underbins large n
+    rice                — (max-min)/(2·n^(1/3)); simple, no assumption
+    sqrt                — (max-min)/√n; simplest
+    doane               — Sturges adjusted for skewness
+    stone               — cross-validation leave-one-out; slower, more accurate
+    knuth               — maximum likelihood; optimal for uniform bins
+    gcd_interval        — GCD of intervals; exact but brittle
+
+Methods returning variable-width edges
+----------------------------------------
+    bayesian_blocks     — dynamic programming; best for non-stationary event data
+"""
+
+from .methods import (
+    auto,
+    freedman_diaconis,
+    scott,
+    sturges,
+    rice,
+    sqrt,
+    doane,
+    stone,
+    knuth,
+    gcd_interval,
+    bayesian_blocks,
+    bin,
+)
+
+__all__ = [
+    "auto",
+    "freedman_diaconis",
+    "scott",
+    "sturges",
+    "rice",
+    "sqrt",
+    "doane",
+    "stone",
+    "knuth",
+    "gcd_interval",
+    "bayesian_blocks",
+    "bin",
+]