exactsampler 0.1.0__py3-none-any.whl

exactsampler/__init__.py

@@ -0,0 +1,7 @@
+"""exactsampler: exact Fisher p-values for r x c tables (free core)."""
+
+from ._fisher import fisher_exact_rc
+
+__version__ = "0.1.0"
+
+__all__ = ["fisher_exact_rc", "__version__"]

exactsampler/_fisher.py

@@ -0,0 +1,112 @@
+"""Exact Fisher test p-values for r x c contingency tables (free core).
+
+``scipy.stats.fisher_exact`` only handles 2x2 tables.  The function here
+generalizes Fisher's exact test to arbitrary r x c tables.
+
+The p-value follows Fisher's definition: under the null of independence
+conditional on the margins, each table has probability
+
+    P(X) = prod(r_i!) prod(c_j!) / (N! prod(X_ij!))
+
+(the multivariate hypergeometric law); the p-value is the total null
+probability of all tables whose probability is no larger than the observed
+table's.  For 2x2 tables this reproduces ``scipy.stats.fisher_exact``
+(two-sided) exactly.
+"""
+
+import math
+
+import numpy as np
+
+from ._tables import _count_upper_bound, enumerate_tables
+
+__all__ = ["fisher_exact_rc"]
+
+_PAID_URL = "https://groundplane0.gumroad.com/l/priui"
+
+# Enumeration budget (tables).  Tables whose estimated table count exceeds
+# this are refused up front instead of hanging; the estimate itself costs
+# O(r + c), so the refusal is always fast.
+#
+# Why 175,000: the tightest legitimate case in the test suite (3x5, N=16)
+# has an estimated bound of exactly 150,000, so the budget must sit above
+# that or real tables get refused.  175,000 keeps ~17 percent headroom
+# above it while sitting well below the red-team hang cases (bounds in the
+# hundreds of millions), so the safety fix is intact.  It is deliberately
+# tighter than the paid product's 200,000 cap: the free tier should drive
+# paid conversion, not replace it.  The bound never undercounts (see the
+# soundness test), so the true enumerated count at the boundary is
+# typically far below 175,000 and enumeration stays fast.
+_MAX_TABLES = 175_000
+
+
+def fisher_exact_rc(table):
+    """Exact Fisher test p-value for a general r x c contingency table.
+
+    Parameters
+    ----------
+    table : array_like, shape (r, c)
+        Observed counts (nonnegative integers).
+
+    Returns
+    -------
+    float
+        Two-sided exact p-value: total null probability of all tables with
+        the same margins whose probability is <= the observed table's.
+
+    Notes
+    -----
+    Enumerates every table with the observed margins, so it is only
+    practical for small tables.  Two up-front refusals keep it from
+    hanging: tables with more than 8 degrees of freedom
+    (``(r-1) * (c-1) > 8``) are refused on shape, and tables whose
+    estimated enumeration cost exceeds 175,000 tables are refused on
+    cost (the estimate is O(r + c), so the refusal itself is instant).
+
+    Tie classification (which tables count as "as or more extreme") is done
+    in exact integer arithmetic (no floating-point tolerance), so the
+    result is the true Fisher p-value up to summation rounding.
+    """
+    T = np.asarray(table)
+    if T.ndim != 2:
+        raise ValueError("table must be 2-dimensional")
+    if np.any(T < 0):
+        raise ValueError("table entries must be nonnegative")
+    if not np.all(np.isfinite(T)):
+        raise ValueError("table entries must be finite")
+    if not np.all(np.equal(np.mod(T, 1), 0)):
+        raise ValueError("table entries must be integers")
+    T = T.astype(np.int64)
+    r = tuple(int(v) for v in T.sum(axis=1))
+    c = tuple(int(v) for v in T.sum(axis=0))
+    if (len(r) - 1) * (len(c) - 1) > 8:
+        raise ValueError(
+            f"table too large to enumerate exactly ({len(r)}x{len(c)}); "
+            "the full version ($30, one-time) adds a Monte Carlo exact "
+            f"test for large tables: {_PAID_URL}"
+        )
+    if _count_upper_bound(r, c, _MAX_TABLES) > _MAX_TABLES:
+        raise ValueError(
+            "Free version refuses tables whose estimated enumeration cost "
+            "exceeds 175,000 tables (the estimate is a conservative upper "
+            "bound, so the true table count is lower). "
+            "The full version ($30, one-time) adds the exactly-uniform "
+            "fixed-margin table sampler and the Monte Carlo exact test for "
+            "tables too large to enumerate: "
+            "https://groundplane0.gumroad.com/l/priui"
+        )
+    # Exact tie classification in integer arithmetic: the common factor
+    # prod(r_i!) prod(c_j!) / N! cancels, so
+    #     P(X) <= P(obs)  <=>  prod(X_ij!) >= prod(obs_ij!).
+    obs_w = math.prod(math.factorial(int(v)) for v in T.flat)
+    logps = []
+    extreme = []
+    for X in enumerate_tables(r, c):
+        w = math.prod(math.factorial(int(v)) for v in X.flat)
+        extreme.append(w >= obs_w)
+        # log P(X) up to the cancelled common factor (lgamma: no overflow)
+        logps.append(-math.fsum(math.lgamma(int(v) + 1) for v in X.flat))
+    m = max(logps)
+    norm = m + math.log(math.fsum(math.exp(lp - m) for lp in logps))
+    p = math.fsum(math.exp(lp - norm) for lp, ex in zip(logps, extreme) if ex)
+    return min(1.0, max(0.0, p))

exactsampler/_tables.py

@@ -0,0 +1,117 @@
+"""Table enumeration for the free exactsampler core.
+
+This is the free subset of the table machinery: everything
+:func:`exactsampler.fisher_exact_rc` needs to enumerate Omega(r, c),
+and nothing else.  The uniform sampler, the table counter, and the
+Monte Carlo test live in the paid version only.
+"""
+
+import math
+import numbers
+
+import numpy as np
+
+__all__ = ["enumerate_tables"]
+
+
+def _to_int_margin_value(x, name):
+    """Coerce one margin entry to int, rejecting non-integers loudly."""
+    if isinstance(x, numbers.Integral):
+        return int(x)
+    if isinstance(x, float) and x.is_integer():
+        return int(x)
+    raise ValueError(f"{name} must be integers; got {x!r}")
+
+
+def _validate_margins(row_sums, col_sums):
+    """Return ``(r, c)`` as tuples of ints, raising on bad input."""
+    try:
+        r = tuple(_to_int_margin_value(x, "row_sums") for x in row_sums)
+        c = tuple(_to_int_margin_value(x, "col_sums") for x in col_sums)
+    except TypeError as exc:
+        raise ValueError("margins must be sequences of integers") from exc
+    if any(x < 0 for x in r) or any(x < 0 for x in c):
+        raise ValueError("margins must be nonnegative")
+    if sum(r) != sum(c):
+        raise ValueError(
+            f"row sums (total {sum(r)}) and column sums (total {sum(c)}) "
+            "must have equal totals"
+        )
+    return r, c
+
+
+def _feasible_rows(total, caps):
+    """Yield every tuple ``x`` with ``sum(x) == total`` and ``0 <= x[j] <= caps[j]``."""
+    caps = tuple(caps)
+    if not caps:
+        if total == 0:
+            yield ()
+        return
+    first, rest = caps[0], caps[1:]
+    for v in range(0, min(first, total) + 1):
+        for tail in _feasible_rows(total - v, rest):
+            yield (v,) + tail
+
+
+def _as_2d(table, m, n):
+    arr = np.asarray(table, dtype=np.int64).reshape(m, n)
+    return arr
+
+
+def _count_upper_bound(row_sums, col_sums, budget):
+    """Cheap upper bound on the number of tables with the given margins.
+
+    Every row of a feasible table is a weak composition of its row sum into
+    ``len(col_sums)`` parts, so the number of tables is at most
+    ``prod_i C(r_i + ncols - 1, ncols - 1)``; the same holds with rows and
+    columns swapped, and the smaller of the two bounds is used.  Evaluated
+    in log space with early exit, so this costs O(r + c) cheap operations
+    even for enormous margins (it never enumerates anything).
+
+    Returns an int: the bound itself, or ``budget + 1`` when the bound is
+    known to exceed ``budget`` (the exact value is then irrelevant, so it
+    is not computed).
+    """
+    r = tuple(x for x in row_sums if x > 0)
+    c = tuple(x for x in col_sums if x > 0)
+    if not r or not c or len(r) == 1 or len(c) == 1:
+        return 1
+    log_budget = math.log(budget)
+    best = None
+    for margins, nparts in ((r, len(c)), (c, len(r))):
+        k = nparts - 1
+        total = 0.0
+        for m in margins:
+            # log C(m + k, k); lgamma is O(1) and overflow-free
+            total += math.lgamma(m + k + 1) - math.lgamma(k + 1) - math.lgamma(m + 1)
+            if total > log_budget:
+                break
+        if best is None or total < best:
+            best = total
+    if best > log_budget:
+        return budget + 1
+    return max(1, int(math.exp(best)))
+
+
+def enumerate_tables(row_sums, col_sums):
+    """Yield every table in Omega(r, c) as a 2-D ``numpy`` int array.
+
+    Only feasible for small tables (the number of tables grows
+    exponentially).  Used here for exact tests.
+    """
+    r, c = _validate_margins(row_sums, col_sums)
+    m, n = len(r), len(c)
+
+    def rec(rows_left, cols_left, acc):
+        if not rows_left:
+            if all(x == 0 for x in cols_left):
+                yield _as_2d(acc, m, n)
+            return
+        for x in _feasible_rows(rows_left[0], tuple(cols_left)):
+            yield from rec(
+                rows_left[1:],
+                [cj - xj for cj, xj in zip(cols_left, x)],
+                acc + [x],
+            )
+
+    yield from rec(list(r), list(c), [])

exactsampler-0.1.0.dist-info/METADATA

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: exactsampler
+Version: 0.1.0
+Summary: Exact Fisher p-values for r-by-c contingency tables (free core)
+Author: Groundplane Labs
+License: MIT
+Project-URL: Homepage, https://groundplane0.gumroad.com/l/priui
+Keywords: fisher exact test,contingency table,exact test,statistics,biostatistics
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Dynamic: license-file
+
+# exactsampler
+
+Free core of ExactSampler: exact Fisher p-values for r-by-c tables.
+
+**The problem**
+Your contingency table is bigger than 2x2 and you need an exact p-value. scipy's `fisher_exact` stops at 2x2. Your options are: approximate it and hope, learn R, or pip install this.
+
+**What it does**
+`fisher_exact_rc(table)` computes the exact two-sided Fisher p-value for r-by-c tables of modest size by enumerating every table with the observed margins. Ties are classified in exact integer arithmetic, so the result is the true p-value up to summation rounding. On 2x2 tables it agrees with scipy to 1e-14. Search terms: Fisher's exact test rxc Python, exact p-value contingency table Python, fisher exact r x c table.
+
+**Limits**
+Exact enumeration is for small-to-moderate tables. Tables beyond 8 degrees of freedom are refused outright instead of hanging, as are tables whose estimated enumeration cost exceeds 175,000 tables (the estimate is a conservative upper bound on the true count; a balanced 2x2 table refuses around N=836). This free core has no uniform table sampler, no Monte Carlo exact test, and no CLI.
+
+**Install**
+
+```bash
+pip install exactsampler
+```
+
+Needs Python 3.9 or newer and NumPy.
+
+```python
+from exactsampler import fisher_exact_rc
+print(fisher_exact_rc([[2, 3], [3, 2]]))
+```
+
+This is the free core: exact Fisher p-values for r-by-c tables. The full version ($30, one-time) adds the exactly-uniform fixed-margin table sampler and the Monte Carlo exact test for tables too large to enumerate: https://groundplane0.gumroad.com/l/priui

exactsampler-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+exactsampler/__init__.py,sha256=nIDWVgv2IlEjQpzwukDzNWXzYRvf1VaO_XjIbGwl6Cg,179
+exactsampler/_fisher.py,sha256=lW0dMs3tBODS09U5OtY6f4WWFiMG_lkQ7UnPEnjWNMQ,4784
+exactsampler/_tables.py,sha256=_tL7aoBiPZLANXXrRfh1wdwbjBQGocyqoTKXICjQ6nI,4021
+exactsampler-0.1.0.dist-info/licenses/LICENSE,sha256=E-nK1L0MERx8owbskcU4J6x8ivUWVIY6wynWY6SZZSw,1073
+exactsampler-0.1.0.dist-info/METADATA,sha256=ef5f2Vn3HQjW5dIkhVtFL-H7AZCHwyggo3gZAfbvDXE,2217
+exactsampler-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+exactsampler-0.1.0.dist-info/top_level.txt,sha256=FlieebkKb-mE4ESN-VDLjrd_WZB0WG8o6KEDWxOywG4,13
+exactsampler-0.1.0.dist-info/RECORD,,

exactsampler-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

exactsampler-0.1.0.dist-info/licenses/LICENSE

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

exactsampler-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+exactsampler