catpie 0.1.0__py3-none-any.whl

catpie/__init__.py

@@ -0,0 +1,193 @@
+"""
+catpie - Computerized Adaptive Testing (CAT) in pure Python.
+
+A faithful translation of the most relevant subset of the R package ``catR``:
+the 4PL item response function, EAP/BM/ML/WL ability estimation with standard
+errors, and MFI/bOpt item selection, plus the simulation helpers
+``genPattern``, ``checkStopRule`` and a minimal ``randomCAT`` loop.
+
+This is a Python port of the R package ``catR`` (and mirrors the sibling
+JavaScript port ``catjs-irt``). It is not written or endorsed by the catR
+authors. Numbers are computed with the exact same formulas and grid as catR
+(defaults: D=1, priorDist="norm", priorPar=(0,1), parInt=(-4,4,33), trapezoid
+integration over 33 points), so results match catR to floating point precision
+for the same inputs.
+
+An "item" is a 4-tuple ``(a, b, c, d)`` (discrimination, difficulty, guessing,
+inattention). Item indices are 0-indexed throughout the public API.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple, Optional, Sequence, Tuple
+
+from .eap import eapEst, eapSem
+from .estimators import semTheta, thetaEst
+from .irf import IiResult, Item, JiResult, PiResult, ii, ji, pi
+from .math import (
+    OptimizeResult,
+    dnorm,
+    integrateCatR,
+    linspace,
+    optimizeScalar,
+    qnorm,
+    uniroot,
+)
+from .selection import NextItemResult, nextItem
+from .simulation import (
+    RandomCatResult,
+    StopRuleResult,
+    checkStopRule,
+    genPattern,
+    randomCAT,
+    simulateRespondents,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # IRF
+    "pi",
+    "ii",
+    "ji",
+    "PiResult",
+    "IiResult",
+    "JiResult",
+    # estimation
+    "eapEst",
+    "eapSem",
+    "thetaEst",
+    "semTheta",
+    # selection
+    "nextItem",
+    "NextItemResult",
+    # simulation
+    "genPattern",
+    "simulateRespondents",
+    "checkStopRule",
+    "randomCAT",
+    "StopRuleResult",
+    "RandomCatResult",
+    # high-level helpers
+    "estimateTheta",
+    "selectNextItem",
+    "ThetaResult",
+    # math helpers (mirror catR/R base functions)
+    "dnorm",
+    "linspace",
+    "integrateCatR",
+    "qnorm",
+    "uniroot",
+    "optimizeScalar",
+    "OptimizeResult",
+    "__version__",
+]
+
+
+class ThetaResult(NamedTuple):
+    """Ability estimate and its standard error (high-level helper)."""
+
+    theta: float
+    se: float
+
+
+def estimateTheta(
+    itemBank: Sequence[Item],
+    administered: Sequence[int],
+    responses: Sequence[int],
+    method: str = "EAP",
+    priorDist: str = "norm",
+    priorPar: Tuple[float, float] = (0, 1),
+    D: float = 1.0,
+    range: Tuple[float, float] = (-4, 4),
+    parInt: Tuple[float, float, int] = (-4, 4, 33),
+    semType: str = "classic",
+) -> ThetaResult:
+    """
+    Estimate ability and its standard error from the items given so far.
+
+    This is the highest-level estimation helper: hand it the whole item bank,
+    the indices of the items already administered, and the person's 0/1
+    responses, and you get back ``(theta, se)`` in one call. It is exactly the
+    helper the EWM experiment's ``estimate_theta_catr(...)`` uses.
+
+    Args:
+        itemBank: The full item bank, as ``(a, b, c, d)`` tuples.
+        administered: 0-based indices (into ``itemBank``) of the items
+            administered so far.
+        responses: 0/1 responses in the same order as ``administered``.
+        method: Estimation method (default ``"EAP"``; also ``"BM"``,
+            ``"ML"``, ``"WL"``).
+        priorDist: Prior distribution (``"norm"`` default).
+        priorPar: Prior parameters (default ``(0, 1)``).
+        D: Scale constant (default ``1.0``).
+        range: Search interval for BM/ML/WL (default ``(-4, 4)``).
+        parInt: EAP integration grid (default ``(-4, 4, 33)``).
+        semType: ``"classic"`` (default) SE form.
+
+    Returns:
+        A :class:`ThetaResult` with fields ``theta`` and ``se``. If no items
+        have been administered yet, returns the prior estimate ``(0.0, inf)``.
+    """
+    if len(administered) == 0:
+        return ThetaResult(0.0, float("inf"))
+    it = [itemBank[i] for i in administered]
+    theta = thetaEst(
+        it,
+        responses,
+        method=method,
+        priorDist=priorDist,
+        priorPar=priorPar,
+        D=D,
+        range=range,
+        parInt=parInt,
+    )
+    se = semTheta(
+        theta,
+        it,
+        responses,
+        method=method,
+        priorDist=priorDist,
+        priorPar=priorPar,
+        D=D,
+        parInt=parInt,
+        semType=semType,
+    )
+    return ThetaResult(theta, se)
+
+
+def selectNextItem(
+    itemBank: Sequence[Item],
+    theta: float,
+    administered: Sequence[int],
+    criterion: str = "MFI",
+    randomesque: int = 1,
+    D: float = 1.0,
+) -> NextItemResult:
+    """
+    Select the next item to administer (default criterion: MFI).
+
+    High-level wrapper around :func:`nextItem` that makes the most common call
+    shorter. It is exactly the helper the EWM experiment's
+    ``select_next_item_catr(...)`` uses.
+
+    Args:
+        itemBank: The full item bank, as ``(a, b, c, d)`` tuples.
+        theta: Current ability estimate (a float, typically ``[-4, 4]``).
+        administered: 0-based indices of the items already administered (they
+            will not be selected again).
+        criterion: ``"MFI"`` (default) or ``"bOpt"``.
+        randomesque: Only the catR default ``1`` is supported.
+        D: Scale constant (default ``1.0``).
+
+    Returns:
+        A :class:`NextItemResult`; see :func:`nextItem` for its fields.
+    """
+    return nextItem(
+        itemBank,
+        theta,
+        administered,
+        criterion=criterion,
+        randomesque=randomesque,
+        D=D,
+    )

catpie/eap.py

@@ -0,0 +1,158 @@
+"""
+Expected A Posteriori (EAP) estimation, mirroring catR's ``eapEst()`` and
+``eapSem()`` exactly (including the grid, the prior and the trapezoid
+integration via ``integrate.catR``).
+
+Supported priors (catR's ``priorDist``): "norm" (N(priorPar[0], priorPar[1])),
+"unif" (uniform over priorPar), "Jeffreys" (weight sqrt(sum(Ii))).
+
+This mirrors catjs-irt's ``src/eap.js``.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Callable, Sequence, Tuple
+
+from .irf import Item, ii, pi
+from .math import dnorm, integrateCatR, linspace
+
+
+def priorWeight(
+    s: float,
+    priorDist: str,
+    priorPar: Tuple[float, float],
+    it: Sequence[Item],
+    D: float = 1.0,
+) -> float:
+    """
+    Prior density term used in the EAP integrand, matching catR's
+    ``switch(...)`` inside ``eapEst``/``eapSem``. For "norm" returns
+    ``dnorm(s)``; for "unif" returns ``dunif(s)`` (1/(b-a) inside [a, b], 0
+    outside); for "Jeffreys" returns ``sqrt(sum(Ii(s, it)))``.
+    """
+    if priorDist == "norm":
+        return dnorm(s, priorPar[0], priorPar[1])
+    if priorDist == "unif":
+        a, b = priorPar[0], priorPar[1]
+        return 1.0 / (b - a) if a <= s <= b else 0.0
+    if priorDist == "Jeffreys":
+        return math.sqrt(sum(ii(s, item, D).Ii for item in it))
+    raise ValueError("eapEst: priorDist %r not implemented" % (priorDist,))
+
+
+def makeLikelihood(
+    it: Sequence[Item], x: Sequence[int], D: float = 1.0
+) -> Callable[[float], float]:
+    """
+    Build the likelihood L(th) = prod_i P_i^x_i * (1 - P_i)^(1 - x_i),
+    exactly as in catR's ``eapEst``:
+
+        L <- function(th, it, x) prod(Pi(th, it, D=D)$Pi^x *
+                                     (1-Pi(th, it, D=D)$Pi)^(1-x))
+    """
+    def likelihood(th: float) -> float:
+        res = 1.0
+        for i, item in enumerate(it):
+            P = pi(th, item, D).P
+            res *= P ** x[i] * (1 - P) ** (1 - x[i])
+        return res
+
+    return likelihood
+
+
+def eapEst(
+    it: Sequence[Item],
+    x: Sequence[int],
+    D: float = 1.0,
+    priorDist: str = "norm",
+    priorPar: Tuple[float, float] = (0, 1),
+    lower: float = -4,
+    upper: float = 4,
+    nqp: int = 33,
+) -> float:
+    """
+    Ability estimate by Expected A Posteriori (EAP) estimation.
+
+    EAP is a *Bayesian* estimate: it combines what the responses tell us (the
+    likelihood) with a *prior* belief about the ability distribution. It is the
+    most robust of the implemented estimators and the default choice of this
+    package (and of the EWM experiment).
+
+    The estimate is computed by numerical integration over a grid of ability
+    values (catR's default: 33 points from ``-4`` to ``4``), so the result is
+    always within ``[lower, upper]``.
+
+    Args:
+        it: The items that were administered, as a list of ``(a, b, c, d)``
+            tuples. Length must equal ``len(x)``.
+        x: The responses, as 0/1 integers (1 = correct) in the same order as
+            ``it``.
+        D: Scale constant (default ``1.0``).
+        priorDist: The prior distribution, one of ``"norm"`` (normal),
+            ``"unif"`` (uniform) or ``"Jeffreys"``.
+        priorPar: Prior parameters. For ``"norm"``: ``(mean, sd)`` — catR
+            default ``(0, 1)`` (standard normal). For ``"unif"``: ``(lower,
+            upper)`` of the uniform interval.
+        lower: Lower bound of the integration grid (default ``-4``).
+        upper: Upper bound of the integration grid (default ``4``).
+        nqp: Number of quadrature points in the grid (catR default ``33``).
+
+    Returns:
+        The estimated ability ``theta`` (a float, always within
+        ``[lower, upper]``).
+    """
+    L = makeLikelihood(it, x, D)
+    X = linspace(lower, upper, nqp)
+
+    def w(s: float) -> float:
+        return priorWeight(s, priorDist, priorPar, it, D)
+
+    g = [s * w(s) * L(s) for s in X]
+    h = [w(s) * L(s) for s in X]
+    return integrateCatR(X, g) / integrateCatR(X, h)
+
+
+def eapSem(
+    thEst: float,
+    it: Sequence[Item],
+    x: Sequence[int],
+    D: float = 1.0,
+    priorDist: str = "norm",
+    priorPar: Tuple[float, float] = (0, 1),
+    lower: float = -4,
+    upper: float = 4,
+    nqp: int = 33,
+) -> float:
+    """
+    Standard error of an EAP ability estimate.
+
+    The standard error tells you how confident you can be in the ability
+    estimate :func:`eapEst`: smaller = more confidence. It is the standard
+    deviation of the posterior distribution, computed by the same numerical
+    integration over the grid.
+
+    Args:
+        thEst: The ability estimate (the output of :func:`eapEst`).
+        it: The administered items, as ``(a, b, c, d)`` tuples.
+        x: The responses (0/1), same order as ``it``.
+        D: Scale constant (default ``1.0``).
+        priorDist: Prior distribution, ``"norm"`` / ``"unif"`` / ``"Jeffreys"``.
+        priorPar: Prior parameters (see :func:`eapEst`).
+        lower: Lower bound of the integration grid (default ``-4``).
+        upper: Upper bound of the integration grid (default ``4``).
+        nqp: Number of quadrature points (catR default ``33``).
+
+    Returns:
+        The standard error (a non-negative float; typically a few tenths, and
+        smaller after more informative items are administered).
+    """
+    L = makeLikelihood(it, x, D)
+    X = linspace(lower, upper, nqp)
+
+    def w(s: float) -> float:
+        return priorWeight(s, priorDist, priorPar, it, D)
+
+    g = [(s - thEst) ** 2 * w(s) * L(s) for s in X]
+    h = [w(s) * L(s) for s in X]
+    return math.sqrt(integrateCatR(X, g) / integrateCatR(X, h))

catpie/estimators.py

@@ -0,0 +1,312 @@
+"""
+Ability (theta) estimation and its standard error, mirroring catR's
+``thetaEst()`` and ``semTheta()`` for the dichotomous model:
+
+  - method:     "EAP" | "BM" | "ML" | "WL"
+  - priorDist:  "norm" | "unif" | "Jeffreys"  (used by EAP and BM)
+  - defaults:   D=1, priorPar=(0,1), parInt=(-4,4,33), range=(-4,4)
+
+The non-EAP methods replicate catR's exact algorithm: solve the score equation
+T(th) = r0(th) + r(th) = 0 by bisection (R's ``uniroot``) over ``range``, with
+catR's ``optimize()``-based fallback when T does not change sign.
+
+This mirrors catjs-irt's ``src/estimators.js``.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import NamedTuple, Optional, Sequence, Tuple, Union
+
+from .eap import eapEst, eapSem
+from .irf import Item, ii, ji, pi
+from .math import OptimizeResult, _sqrt, optimizeScalar, uniroot
+
+Number = Union[int, float]
+
+
+class SumDersResult(NamedTuple):
+    """Summed information and its derivatives over a set of items."""
+
+    Ii: float
+    dIi: float
+    d2Ii: float
+
+
+def _is_missing(v: object) -> bool:
+    """True for NaN/None, matching catjs-irt's NaN/undefined/null filter."""
+    if v is None:
+        return True
+    try:
+        return math.isnan(v)  # type: ignore[arg-type]
+    except TypeError:
+        return False
+
+
+def dropMissing(
+    it: Sequence[Item], x: Sequence[Number]
+) -> Tuple[Sequence[Item], Sequence[Number]]:
+    """
+    Filter out NaN/None responses and the corresponding items, matching catR's
+    ``thetaEst``: ``ind <- which(!is.na(x)); it <- it[ind, ]; x <- x[ind]``.
+    """
+    idx = [i for i, v in enumerate(x) if not _is_missing(v)]
+    return [it[i] for i in idx], [x[i] for i in idx]
+
+
+def sumIi(th: float, it: Sequence[Item], D: float) -> float:
+    """Sum of item information at ``th`` over ``it``."""
+    return sum(ii(th, item, D).Ii for item in it)
+
+
+def sumDers(th: float, it: Sequence[Item], D: float) -> SumDersResult:
+    """Sum of item information derivatives at ``th`` over ``it``."""
+    Ii = 0.0
+    dIi = 0.0
+    d2Ii = 0.0
+    for item in it:
+        res = ii(th, item, D)
+        Ii += res.Ii
+        dIi += res.dIi
+        d2Ii += res.d2Ii
+    return SumDersResult(Ii, dIi, d2Ii)
+
+
+def r0(
+    th: float,
+    it: Sequence[Item],
+    method: str = "BM",
+    priorDist: str = "norm",
+    priorPar: Tuple[float, float] = (0, 1),
+    D: float = 1.0,
+) -> float:
+    """catR's ``r0`` term (prior / method correction) in the score equation."""
+    if method == "ML":
+        return 0.0
+    if method == "WL":
+        sumJ = sum(ji(th, item, D).Ji for item in it)
+        return sumJ / (2 * sumIi(th, it, D))
+    # BM
+    if priorDist == "norm":
+        return (priorPar[0] - th) / priorPar[1] ** 2
+    if priorDist == "unif":
+        return 0.0
+    if priorDist == "Jeffreys":
+        ders = sumDers(th, it, D)
+        return ders.dIi / (2 * ders.Ii)
+    raise ValueError("thetaEst: priorDist %r not implemented" % (priorDist,))
+
+
+def r(th: float, it: Sequence[Item], x: Sequence[Number], D: float = 1.0) -> float:
+    """catR's ``r`` term: sum of dP*(x - P)/(P*Q) over items."""
+    res = 0.0
+    for i, item in enumerate(it):
+        pr = pi(th, item, D)
+        P = pr.P
+        Q = 1 - P
+        dP = pr.dP
+        res += (dP * (x[i] - P)) / (P * Q)
+    return res
+
+
+def thetaEst(
+    it: Sequence[Item],
+    x: Sequence[Number],
+    method: str = "EAP",
+    priorDist: str = "norm",
+    priorPar: Tuple[float, float] = (0, 1),
+    D: float = 1.0,
+    range: Tuple[float, float] = (-4, 4),
+    parInt: Tuple[float, float, int] = (-4, 4, 33),
+) -> float:
+    """
+    Estimate a person's ability (theta) from their responses.
+
+    This is the main estimation function. Give it the items that were
+    administered and the person's 0/1 responses, and it returns the best
+    estimate of their ability. The higher the ability, the "better" the
+    person performed.
+
+    Four estimation methods are available:
+
+    - ``"EAP"`` (default): Bayesian, most robust, uses the prior; the result
+      always lies within the integration grid (default ``[-4, 4]``).
+    - ``"BM"``: Bayesian modal estimate (posterior maximum), uses the prior.
+    - ``"ML"``: maximum likelihood; uses only the responses (no prior). Can
+      be extreme (and is unstable on degenerate item banks, exactly like catR).
+    - ``"WL"``: weighted likelihood; reduces the bias of ML.
+
+    Missing responses (``NaN``/``None``) and their items are ignored.
+
+    Args:
+        it: The administered items as ``(a, b, c, d)`` tuples (same length as
+            ``x``).
+        x: The responses as 0/1 integers (1 = correct); ``NaN``/``None``
+            entries are dropped together with the corresponding items.
+        method: One of ``"EAP"`` (default), ``"BM"``, ``"ML"``, ``"WL"``.
+        priorDist: Prior distribution for ``EAP``/``BM``: ``"norm"``
+            (default), ``"unif"``, ``"Jeffreys"``.
+        priorPar: Prior parameters ``(mean, sd)`` for ``"norm"`` (default
+            ``(0, 1)``) or ``(lower, upper)`` for ``"unif"``.
+        D: Scale constant (default ``1.0``).
+        range: The search interval ``(lower, upper)`` for the BM/ML/WL root
+            finding (default ``(-4, 4)``). Not used by EAP.
+        parInt: ``(lower, upper, npoints)`` of the integration grid for EAP
+            (default ``(-4, 4, 33)``).
+
+    Returns:
+        The estimated ability as a float (a higher value = higher estimated
+        ability). For EAP it lies within the integration grid; BM/ML/WL may
+        return a range boundary when no interior root exists (like catR).
+
+    Raises:
+        ValueError: If ``method`` is not one of EAP/BM/ML/WL, or ``priorDist``
+            is not supported.
+    """
+    fit, fx = dropMissing(it, x)
+
+    if method == "EAP":
+        return eapEst(
+            fit,
+            fx,
+            D=D,
+            priorDist=priorDist,
+            priorPar=priorPar,
+            lower=parInt[0],
+            upper=parInt[1],
+            nqp=parInt[2],
+        )
+    if method not in ("BM", "ML", "WL"):
+        raise ValueError("thetaEst: method %r not implemented" % (method,))
+
+    # catR: f is T(th) = r0(th) + r(th), except BM+unif which reduces to ML
+    # and searches over the prior interval.
+    usePrior = not (method == "BM" and priorDist == "unif")
+
+    def f(th: float) -> float:
+        t = r(th, fit, fx, D)
+        if usePrior:
+            return (
+                r0(
+                    th,
+                    fit,
+                    method=method,
+                    priorDist=priorDist,
+                    priorPar=priorPar,
+                    D=D,
+                )
+                + t
+            )
+        return t
+
+    RANGE = priorPar if (method == "BM" and priorDist == "unif") else range
+
+    fLo = f(RANGE[0])
+    fHi = f(RANGE[1])
+    if (fLo < 0 < fHi) or (fLo > 0 > fHi):
+        return uniroot(f, RANGE[0], RANGE[1])
+
+    # catR fallback: minimize f; if min > 0 -> upper bound; maximize; if max < 0
+    # -> lower bound; else root between the argmax and argmin.
+    pr: OptimizeResult = optimizeScalar(f, RANGE[0], RANGE[1])
+    if pr.y > 0:
+        return RANGE[1]
+    pr2: OptimizeResult = optimizeScalar(f, RANGE[0], RANGE[1], maximize=True)
+    if pr2.y < 0:
+        return RANGE[0]
+    lo = min(pr2.x, pr.x)
+    hi = max(pr2.x, pr.x)
+    return uniroot(f, lo, hi)
+
+
+def semTheta(
+    thEst: float,
+    it: Sequence[Item],
+    x: Sequence[Number],
+    method: str = "EAP",
+    priorDist: str = "norm",
+    priorPar: Tuple[float, float] = (0, 1),
+    D: float = 1.0,
+    parInt: Tuple[float, float, int] = (-4, 4, 33),
+    semType: str = "classic",
+    range: Tuple[float, float] = (-4, 4),
+) -> float:
+    """
+    Standard error (SE) of an ability estimate.
+
+    The SE quantifies the uncertainty of an ability estimate :func:`thetaEst`:
+    small SE = confident estimate, large SE = uncertain. It is used by the
+    stopping rules (e.g. stop once ``se`` drops below a threshold) and to build
+    confidence intervals for classification.
+
+    The method should match the one used for estimation (``method=...``).
+
+    Args:
+        thEst: The ability estimate (output of :func:`thetaEst`).
+        it: The administered items as ``(a, b, c, d)`` tuples.
+        x: The responses (0/1); ``NaN``/``None`` are dropped with their items.
+        method: Estimation method: ``"EAP"`` (default), ``"BM"``, ``"ML"``,
+            ``"WL"``.
+        priorDist: Prior distribution for EAP/BM (``"norm"`` default,
+            ``"unif"``, ``"Jeffreys"``).
+        priorPar: Prior parameters (see :func:`thetaEst`).
+        D: Scale constant (default ``1.0``).
+        parInt: Integration grid ``(lower, upper, npoints)`` for EAP (default
+            ``(-4, 4, 33)``).
+        semType: ``"classic"`` (default) or ``"new"`` (only implemented for
+            the classic form in this port).
+        range: Accepted for catR signature parity; not used by the implemented
+            methods.
+
+    Returns:
+        The standard error as a non-negative float. As a rough guide, values
+        below ~0.3 are often considered "precise enough" for adaptive testing.
+
+    Raises:
+        ValueError: If ``method`` is not one of EAP/BM/ML/WL or ``priorDist``
+            is not supported.
+    """
+    fit, fx = dropMissing(it, x)
+
+    if method == "EAP":
+        return eapSem(
+            thEst,
+            fit,
+            fx,
+            D=D,
+            priorDist=priorDist,
+            priorPar=priorPar,
+            lower=parInt[0],
+            upper=parInt[1],
+            nqp=parInt[2],
+        )
+    if method not in ("BM", "ML", "WL"):
+        raise ValueError("semTheta: method %r not implemented" % (method,))
+
+    info = sumIi(thEst, fit, D)
+
+    if method == "ML":
+        return 1.0 / _sqrt(info)
+
+    if method == "WL":
+        # classic: 1/sqrt(info); new: sqrt(info)/abs(info - dr0) -- classic only
+        # is implemented (the catR new-type WL needs Ji derivatives).
+        if semType == "new":
+            dr0wl = 0.0
+            return _sqrt(info) / abs(info - dr0wl)
+        return 1.0 / _sqrt(info)
+
+    # BM
+    if priorDist == "norm":
+        dr0 = -1.0 / priorPar[1] ** 2
+    elif priorDist == "unif":
+        dr0 = 0.0
+    elif priorDist == "Jeffreys":
+        ders = sumDers(thEst, fit, D)
+        dr0 = (ders.d2Ii * ders.Ii - ders.dIi * ders.dIi) / (2 * ders.Ii * ders.Ii)
+    else:
+        raise ValueError("semTheta: priorDist %r not implemented" % (priorDist,))
+
+    if semType == "classic":
+        return 1.0 / _sqrt(info - dr0)
+    return _sqrt(info) / abs(info - dr0)