grecov 0.2.0

Exact confidence intervals for multinomial distributions via Neyman construction

grecov

Efficient Neyman construction for multinomial distributions with the Greedy Coverage algorithm.

Installation

For the IPOPT optimizer (recommended for best results):

pip install grecov[ipopt]

Development

Install in editable mode with test dependencies:

pip install -e ".[test]"

After modifying C++ code in src/ext/, rebuild with:

pip install -e .

Install pre-commit hooks to run ruff and clang-format on every commit:

pip install pre-commit
pre-commit install

Usage

from grecov import multinomial_ci

result = multinomial_ci(
    counts=[10, 10, 20, 60],
    values=[1, 2, 3, 4],
    alpha=0.05,
)
print(f"95% CI: [{result['lower']:.4f}, {result['upper']:.4f}]")

R (via reticulate)

An R package is available in r-package/ that wraps grecov using reticulate.

Installation

# Install reticulate if needed
install.packages("reticulate")

# Install the R package from the local directory
install.packages("r-package", repos = NULL, type = "source")

# Install the grecov Python package into reticulate's Python environment
grecov::install_grecov()

Usage

library(grecov)

result <- multinomial_ci(
  counts = c(10, 10, 20, 60),
  values = c(1, 2, 3, 4),
  alpha = 0.05
)
cat(sprintf("95%% CI: [%.4f, %.4f]\n", result$lower, result$upper))

The low-level BFS function is also available:

bfs <- grecov_bfs(
  p = c(0.1, 0.1, 0.2, 0.6),
  v = c(1, 2, 3, 4),
  s_obs = 330,
  n = 100L
)
cat(sprintf("P(S <= 330) = %.6f\n", bfs$prob_left))

Options

All parameters from the Python API are available:

result <- multinomial_ci(
  counts = c(10, 10, 20, 60),
  values = c(1, 2, 3, 4),
  alpha = 0.10,
  method = "greedy",
  verbose = 1L
)

Pyodide (browser / WebAssembly)

grecov compiles to WebAssembly and runs in the browser via Pyodide. The C++ BFS extension compiles unchanged; cyipopt is not included (the scipy trust-constr fallback is used automatically).

Using in a webpage

The pyodide wheel is attached to each GitHub Release. The following snippet automatically fetches the latest one:

<script src="https://cdn.jsdelivr.net/pyodide/v0.27.7/full/pyodide.js"></script>
<script type="module">
const pyodide = await loadPyodide();
await pyodide.loadPackage(["micropip", "numpy", "scipy"]);

// Find and install the latest pyodide wheel from GitHub Releases
const res = await fetch("https://api.github.com/repos/louisabraham/grecov/releases/latest");
const release = await res.json();
const wheel = release.assets.find(a => a.name.includes("pyodide"));
await pyodide.runPythonAsync(`
    import micropip
    await micropip.install("${wheel.browser_download_url}")
`);

pyodide.runPython(`
from grecov import multinomial_ci
result = multinomial_ci(
    counts=[10, 10, 20, 60],
    values=[1, 2, 3, 4],
    alpha=0.05,
)
print(f"95% CI: [{result['lower']:.4f}, {result['upper']:.4f}]")
`);
</script>

Building the Pyodide wheel locally

pip install pyodide-build
pyodide xbuildenv install
pyodide build

This requires the matching Emscripten version (pyodide config get emscripten_version). Install it via emsdk and source emsdk_env.sh before running pyodide build. The wheel is written to dist/.

Performance

Pyodide/wasm performance is on par with native CPython (~1.0x). Run the comparison benchmark with:

python profiling/bench_pyodide.py