dfbayes 0.1.0__py3-none-any.whl

dfbayes/__init__.py

@@ -0,0 +1,93 @@
+"""Distribution-free Bayesian procedures, ported from R's DFBA 0.1.0.
+
+Phase 1 covers the eleven closed-form core functions.  Phase 2 adds the
+simulation helpers ``dfba_sim_data``, ``dfba_power_curve`` and
+``dfba_bayes_vs_t_power``.
+"""
+
+from __future__ import annotations
+
+from .beta import dfba_beta_bayes_factor, dfba_beta_descriptive
+from .binomial import dfba_binomial
+from .concordance import dfba_bivariate_concordance, dfba_gamma
+from .contrast import dfba_beta_contrast
+from .mann_whitney import dfba_mann_whitney
+from .mcnemar import dfba_mcnemar
+from .median_test import dfba_median_test
+from .results import (
+    BetaContrastOut,
+    BetaDescriptiveOut,
+    BetaOutputDF,
+    BinomialOut,
+    BivariateConcordanceOut,
+    BivariateConcordanceStarOut,
+    DFBAResult,
+    GammaOut,
+    IntervalBFOut,
+    MannWhitneyLargeOut,
+    MannWhitneySmallOut,
+    McnemarOut,
+    MedianTestOut,
+    OutputTable,
+    PointBFOut,
+    PowerCurveOut,
+    SignTestOut,
+    SimDataOut,
+    TPowerOut,
+    WilcoxonLargeOut,
+    WilcoxonSmallOut,
+    results_to_dataframe,
+)
+from .sign_test import dfba_sign_test
+from .simulation import (
+    dfba_bayes_vs_t_power,
+    dfba_power_curve,
+    dfba_sim_data,
+)
+from .wilcoxon import dfba_wilcoxon
+
+__version__ = "0.1.0"
+
+__all__ = [  # noqa: RUF022 - grouped by kind for readability
+    "__version__",
+    # functions
+    "dfba_beta_bayes_factor",
+    "dfba_beta_contrast",
+    "dfba_beta_descriptive",
+    "dfba_binomial",
+    "dfba_bivariate_concordance",
+    "dfba_gamma",
+    "dfba_mann_whitney",
+    "dfba_mcnemar",
+    "dfba_median_test",
+    "dfba_sign_test",
+    "dfba_wilcoxon",
+    # Phase 2 simulation
+    "dfba_sim_data",
+    "dfba_power_curve",
+    "dfba_bayes_vs_t_power",
+    # result objects
+    "DFBAResult",
+    "BetaContrastOut",
+    "BetaDescriptiveOut",
+    "BetaOutputDF",
+    "BinomialOut",
+    "BivariateConcordanceOut",
+    "BivariateConcordanceStarOut",
+    "GammaOut",
+    "IntervalBFOut",
+    "MannWhitneyLargeOut",
+    "MannWhitneySmallOut",
+    "McnemarOut",
+    "MedianTestOut",
+    "OutputTable",
+    "PointBFOut",
+    "PowerCurveOut",
+    "SignTestOut",
+    "SimDataOut",
+    "TPowerOut",
+    "WilcoxonLargeOut",
+    "WilcoxonSmallOut",
+    # batch helpers
+    "results_to_dataframe",
+]

dfbayes/_core.py

@@ -0,0 +1,208 @@
+"""Shared numerical and validation helpers.
+
+The port deliberately mirrors R's scalar behaviour, including division by zero
+(``Inf``/``-Inf``/``NaN``) and the fact that ``is.na(NaN)`` is TRUE.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from scipy.special import betainc, betaincinv, betaln
+
+# ---------------------------------------------------------------------------
+# NA / NaN
+# ---------------------------------------------------------------------------
+
+def is_na(value: Any) -> bool:
+    """R's ``is.na``: TRUE for both NA (None) and NaN."""
+    if value is None:
+        return True
+    try:
+        return bool(np.isnan(value))
+    except (TypeError, ValueError):
+        return False
+
+
+def as_float_vector(values: Any, name: str = "values") -> np.ndarray:
+    """Convert a sequence to a 1-D float array, mapping None to NaN.
+
+    This is the input-side equivalent of R's numeric vector coercion; ``None``
+    and ``NaN`` both become ``NaN`` and are treated as missing.
+    """
+    if values is None:
+        arr = np.array([np.nan], dtype=float)
+    elif isinstance(values, np.ndarray):
+        arr = values.astype(float, copy=False)
+        if arr.ndim == 0:
+            arr = arr.reshape(1)
+    else:
+        try:
+            arr = np.asarray(list(values), dtype=float)
+        except TypeError:
+            # R treats a scalar as a length-1 vector.
+            arr = np.array([float(values)], dtype=float)
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be a one-dimensional vector")
+    return arr
+
+
+def as_scalar(value: Any, name: str) -> float:
+    """Coerce a scalar argument to float, mapping None to NaN."""
+    if value is None:
+        return float("nan")
+    try:
+        return float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be a single numeric value") from exc
+
+
+def rdiv(numerator: float, denominator: float) -> float:
+    """Division with R's semantics: 0/0 -> NaN, x/0 -> +/-Inf."""
+    num = float(numerator)
+    den = float(denominator)
+    if math.isnan(num) or math.isnan(den):
+        return float("nan")
+    if den == 0.0:
+        if num == 0.0:
+            return float("nan")
+        return math.copysign(math.inf, num)
+    return num / den
+
+
+def r_pow(x: float, y: float) -> float:
+    """R's ``^`` for the cases used upstream.
+
+    R evaluates a non-negative integer power by repeated multiplication
+    (``x^4`` is ``((x*x)*x)*x``), not libm ``pow``.  The two differ by one ulp
+    often enough to matter: the Mann-Whitney polynomial subtracts terms of
+    order 1e3 to obtain a result of order 1e-2, so a one-ulp change in ``x^4``
+    is amplified to ~1e-12 in the output.
+    """
+    xf = float(x)
+    yf = float(y)
+    if yf >= 0.0 and yf.is_integer():
+        result = 1.0
+        for _ in range(int(yf)):
+            result *= xf
+        return result
+    return xf ** yf
+
+
+def rseq(start: float, stop: float, by: float, *, n: int | None = None) -> np.ndarray:
+    """Approximate R's ``seq`` for the fixed grids used upstream.
+
+    Upstream only uses ``seq`` with a known number of points (201, 1001, 200,
+    101), so callers pass ``n`` and we use ``linspace``.  The endpoint is
+    included, matching R.
+    """
+    if n is None:
+        raise TypeError("rseq requires n")
+    return np.linspace(start, stop, n)
+
+
+# ---------------------------------------------------------------------------
+# Beta distribution functions (R's pbeta/qbeta/dbeta equivalents)
+# ---------------------------------------------------------------------------
+
+def pbeta(q: float, a: float, b: float) -> float:
+    if is_na(q) or is_na(a) or is_na(b):
+        return float("nan")
+    return float(betainc(a, b, q))
+
+
+def pbeta_vec(q: np.ndarray, a: float, b: float) -> np.ndarray:
+    return betainc(a, b, np.asarray(q, dtype=float))
+
+
+def qbeta(p: float, a: float, b: float) -> float:
+    if is_na(p) or is_na(a) or is_na(b):
+        return float("nan")
+    return float(betaincinv(a, b, p))
+
+
+def qbeta_vec(p: np.ndarray, a: float, b: float) -> np.ndarray:
+    return betaincinv(a, b, np.asarray(p, dtype=float))
+
+
+def dbeta(x: float, a: float, b: float) -> float:
+    """Beta density, including R's boundary conventions."""
+    if is_na(x) or is_na(a) or is_na(b):
+        return float("nan")
+    x = float(x)
+    if x < 0.0 or x > 1.0:
+        return 0.0
+    if x == 0.0:
+        if a < 1.0:
+            return math.inf
+        if a == 1.0:
+            return float(b)
+        return 0.0
+    if x == 1.0:
+        if b < 1.0:
+            return math.inf
+        if b == 1.0:
+            return float(a)
+        return 0.0
+    log_density = (a - 1.0) * math.log(x) + (b - 1.0) * math.log1p(-x) - float(betaln(a, b))
+    return math.exp(log_density)
+
+
+# ---------------------------------------------------------------------------
+# Validation helpers
+# ---------------------------------------------------------------------------
+
+def check_positive_finite(a: Any, b: Any, message: str) -> tuple[float, float]:
+    av = as_scalar(a, "a")
+    bv = as_scalar(b, "b")
+    for value in (av, bv):
+        if math.isnan(value) or math.isinf(value) or value <= 0.0:
+            raise ValueError(message)
+    return av, bv
+
+
+def check_prob_interval(value: Any, *, allow_zero_one: bool, message: str) -> float:
+    p = as_scalar(value, "prob_interval")
+    if math.isnan(p):
+        # R reaches `if (NA)` and raises a base error, not the custom stop().
+        raise ValueError("missing value where TRUE/FALSE needed")
+    if allow_zero_one:
+        if p < 0.0 or p > 1.0:
+            raise ValueError(message)
+    else:
+        if p <= 0.0 or p >= 1.0:
+            raise ValueError(message)
+    return p
+
+
+def check_nonnegative_count(
+    value: Any,
+    name: str,
+    negative_message: str,
+    integer_message: str,
+) -> int | float:
+    """Validate a count in R's order: negativity/NA first, integrality second.
+
+    Preserves whether the caller supplied an int or a float, matching R's
+    observable ``integer`` vs ``double`` distinction for inputs.
+    """
+    if value is None:
+        raise ValueError(negative_message)
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(negative_message) from exc
+    if math.isnan(numeric) or numeric < 0.0:
+        raise ValueError(negative_message)
+    if numeric != round(numeric):
+        raise ValueError(integer_message)
+    if isinstance(value, (int, np.integer)):
+        return int(value)
+    return numeric
+
+
+def result_fields(obj: Any) -> list[tuple[str, Any]]:
+    """Return (name, value) pairs in R slot order."""
+    return [(name, getattr(obj, name)) for name in obj.R_FIELDS]

dfbayes/beta.py

@@ -0,0 +1,209 @@
+"""Beta descriptive statistics and Bayes factors."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+
+from ._core import (
+    as_scalar,
+    check_positive_finite,
+    check_prob_interval,
+    dbeta,
+    pbeta,
+    qbeta,
+    qbeta_vec,
+    r_pow,
+    rdiv,
+)
+from .results import (
+    BetaDescriptiveOut,
+    BetaOutputDF,
+    IntervalBFOut,
+    PointBFOut,
+)
+
+
+def dfba_beta_descriptive(
+    a: float,
+    b: float,
+    prob_interval: float = 0.95,
+) -> BetaDescriptiveOut:
+    """Descriptive statistics for a beta distribution.
+
+    Mirrors ``DFBA::dfba_beta_descriptive``.  An undefined mode or HDI is
+    returned as ``None`` (R stores a logical ``NA`` there).
+    """
+    pi = check_prob_interval(
+        prob_interval,
+        allow_zero_one=True,
+        message="The probability for the interval estimate must be between 0 and 1.",
+    )
+    av, bv = check_positive_finite(
+        a, b,
+        "Both the a and b shape parameters for a beta must be positive and finite",
+    )
+
+    phimean = av / (av + bv)
+    phivariance = (av * bv) / (r_pow(av + bv, 2) * (av + bv + 1))
+    phimedian = qbeta(0.5, av, bv)
+
+    undefined_mode = (av == 1.0 and bv == 1.0) or av < 1.0 or bv < 1.0
+    phimode = None if undefined_mode else (av - 1.0) / (av + bv - 2.0)
+
+    qlequal = qbeta((1.0 - pi) / 2.0, av, bv)
+    qhequal = qbeta(pi + ((1.0 - pi) / 2.0), av, bv)
+
+    if undefined_mode:
+        qlmin = None
+        qhmax = None
+    else:
+        # R: seq(0, 1 - prob_interval, (1 - prob_interval)/1000)
+        alpha_l = np.linspace(0.0, 1.0 - pi, 1001)
+        ql = qbeta_vec(alpha_l, av, bv)
+        qh = qbeta_vec(pi + alpha_l, av, bv)
+        diff = qh - ql
+        index = int(np.argmin(diff))  # first index attaining the minimum
+        qlmin = float(ql[index])
+        qhmax = float(qh[index])
+
+    # R: seq(0, 1, .005) -> 201 points
+    x = np.arange(201, dtype=float) * 0.005
+    density = np.array([dbeta(float(xi), av, bv) for xi in x])
+    cumulative = np.array(
+        [pbeta(float(xi), av, bv) for xi in x]
+    )
+    outputdf = BetaOutputDF(x=x, density=density, cumulative_prob=cumulative)
+
+    return BetaDescriptiveOut(
+        a=av,
+        b=bv,
+        prob_interval=pi,
+        x_mean=phimean,
+        x_median=phimedian,
+        x_mode=phimode,
+        x_variance=phivariance,
+        eti_lower=qlequal,
+        eti_upper=qhequal,
+        hdi_lower=qlmin,
+        hdi_upper=qhmax,
+        outputdf=outputdf,
+    )
+
+
+def dfba_beta_bayes_factor(
+    a_post: float,
+    b_post: float,
+    method: str,
+    H0: Any,
+    a0: float = 1.0,
+    b0: float = 1.0,
+) -> PointBFOut | IntervalBFOut:
+    """Bayes factor for a point or interval null hypothesis."""
+    if method != "point" and method != "interval":
+        raise ValueError("method must be either 'point' or 'interval'")
+
+    a0v, b0v = check_positive_finite(
+        a0, b0, "Both a0 and b0 must be positive and finite."
+    )
+    a_postv = as_scalar(a_post, "a_post")
+    b_postv = as_scalar(b_post, "b_post")
+
+    if (
+        a_postv < a0v
+        or b_postv < b0v
+        or math.isnan(a_postv)
+        or math.isnan(b_postv)
+    ):
+        raise ValueError(
+            "Both a_post and b_post cannot be less than the respective a0 and b0 values"
+        )
+
+    if method == "point":
+        # R checks length(H0), so a length-1 vector is accepted as well as a
+        # scalar.
+        if np.ndim(H0) == 1 and len(H0) == 1:
+            H0 = H0[0]
+        elif np.ndim(H0) != 0:
+            raise ValueError("'H0' must be a single numeric value when method = 'point'")
+        if H0 is None:
+            raise ValueError("missing value where TRUE/FALSE needed")
+        h0 = as_scalar(H0, "H0")
+        if math.isnan(h0):
+            raise ValueError("missing value where TRUE/FALSE needed")
+        if h0 > 1.0 or h0 < 0.0:
+            raise ValueError(
+                "H0 must be greater than or equal to 0 and less than or equal to 1"
+            )
+
+        dprior = dbeta(h0, a0v, b0v)
+        dpost = dbeta(h0, a_postv, b_postv)
+        bf10 = math.inf if dpost == 0.0 else rdiv(dprior, dpost)
+        bf01 = math.inf if dprior == 0.0 else rdiv(dpost, dprior)
+
+        return PointBFOut(
+            method=method,
+            a_post=a_postv,
+            b_post=b_postv,
+            a0=a0v,
+            b0=b0v,
+            BF10=bf10,
+            BF01=bf01,
+            null_hypothesis=h0,
+            dpriorH0=dprior,
+            dpostH0=dpost,
+        )
+
+    # interval
+    if np.ndim(H0) != 1 or len(H0) != 2:
+        raise ValueError(
+            "'H0' must be a vector of two values (lower and upper) when method = 'interval'"
+        )
+    if any(v is None for v in H0):
+        raise ValueError("missing value where TRUE/FALSE needed")
+    lower = as_scalar(H0[0], "H0[0]")
+    upper = as_scalar(H0[1], "H0[1]")
+    if math.isnan(lower) or math.isnan(upper):
+        raise ValueError("missing value where TRUE/FALSE needed")
+    if any(v > 1.0 or v < 0.0 for v in (lower, upper)):
+        raise ValueError(
+            "H0 interval limits must be greater than or equal to 0 and less than or equal to 1"
+        )
+    if lower >= upper:
+        raise ValueError(
+            "When method = 'interval', H0 upper limit must be greater than H0 lower limit"
+        )
+
+    ph0 = pbeta(upper, a0v, b0v) - pbeta(lower, a0v, b0v)
+    ph1 = 1.0 - ph0
+    post_h0 = pbeta(upper, a_postv, b_postv) - pbeta(lower, a_postv, b_postv)
+    post_h1 = 1.0 - post_h0
+
+    bf10 = (
+        math.inf
+        if post_h0 == 0.0
+        else rdiv(rdiv(1.0, post_h0) - 1.0, rdiv(1.0, ph0) - 1.0)
+    )
+    bf01 = (
+        math.inf
+        if post_h1 == 0.0
+        else rdiv(rdiv(1.0, ph0) - 1.0, rdiv(1.0, post_h0) - 1.0)
+    )
+
+    return IntervalBFOut(
+        method=method,
+        a_post=a_postv,
+        b_post=b_postv,
+        a0=a0v,
+        b0=b0v,
+        BF10=bf10,
+        BF01=bf01,
+        H0lower=lower,
+        H0upper=upper,
+        pH0=ph0,
+        pH1=ph1,
+        postH0=post_h0,
+        postH1=post_h1,
+    )

dfbayes/binomial.py

@@ -0,0 +1,57 @@
+"""Bayesian binomial rate inference."""
+
+from __future__ import annotations
+
+from ._core import check_nonnegative_count, check_positive_finite, check_prob_interval
+from .beta import dfba_beta_descriptive
+from .results import BinomialOut
+
+
+def dfba_binomial(
+    n1: float,
+    n2: float,
+    a0: float = 1.0,
+    b0: float = 1.0,
+    prob_interval: float = 0.95,
+) -> BinomialOut:
+    """Bayesian inference for a binomial rate parameter.
+
+    ``n1`` and ``n2`` must be non-negative integers; ``a0``/``b0`` must be
+    positive and finite.  NA/NaN anywhere raises ``ValueError``, matching R.
+    """
+    a0v, b0v = check_positive_finite(
+        a0, b0, "Both a0 and b0 must be positive and finite"
+    )
+    pi = check_prob_interval(
+        prob_interval,
+        allow_zero_one=False,
+        message="prob_interval must be greater than 0 and less than 1",
+    )
+    n1v = check_nonnegative_count(
+        n1, "n1", "Neither n1 nor n2 can be negative", "n1 and n2 must be integers"
+    )
+    n2v = check_nonnegative_count(
+        n2, "n2", "Neither n1 nor n2 can be negative", "n1 and n2 must be integers"
+    )
+
+    a_post = n1v + a0v
+    b_post = n2v + b0v
+
+    descriptive = dfba_beta_descriptive(a_post, b_post, prob_interval=pi)
+
+    return BinomialOut(
+        n1=n1v,
+        n2=n2v,
+        a0=a0v,
+        b0=b0v,
+        prob_interval=pi,
+        a_post=a_post,
+        b_post=b_post,
+        phimean=descriptive.x_mean,
+        phimedian=descriptive.x_median,
+        phimode=descriptive.x_mode,
+        eti_lower=descriptive.eti_lower,
+        eti_upper=descriptive.eti_upper,
+        hdi_lower=descriptive.hdi_lower,
+        hdi_upper=descriptive.hdi_upper,
+    )