sensopy 0.0.1__py3-none-any.whl

sensopy/__init__.py

@@ -0,0 +1,12 @@
+"""Top-level package for SensoPy."""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from .discrimination import DiscriminationTest
+
+__version__ = version(__name__)
+"""Package version"""
+
+__all__ = ["DiscriminationTest"]

sensopy/discrimination/__init__.py

@@ -0,0 +1,50 @@
+"""Discrimination tests."""
+
+from __future__ import annotations
+
+from .discrimination import DiscriminationTest, SimulationResults, Statistic, TestResults
+from .methods import (
+    DUAL_PAIR,
+    DUO_TRIO,
+    FOUR_AFC,
+    SPECIFIED_TETRAD,
+    THREE_AFC,
+    TRIANGLE,
+    TWO_AFC,
+    UNSPECIFIED_TETRAD,
+    DualPairMethod,
+    DuoTrioMethod,
+    FourAFCMethod,
+    MPlusNMethod,
+    MultipleAFCMethod,
+    SpecifiedTetradMethod,
+    ThreeAFCMethod,
+    TriangleMethod,
+    TwoAFCMethod,
+    UnspecifiedTetrad,
+)
+
+__all__ = [
+    "DUAL_PAIR",
+    "DUO_TRIO",
+    "FOUR_AFC",
+    "SPECIFIED_TETRAD",
+    "THREE_AFC",
+    "TRIANGLE",
+    "TWO_AFC",
+    "UNSPECIFIED_TETRAD",
+    "DiscriminationTest",
+    "DualPairMethod",
+    "DuoTrioMethod",
+    "FourAFCMethod",
+    "MPlusNMethod",
+    "MultipleAFCMethod",
+    "SimulationResults",
+    "SpecifiedTetradMethod",
+    "Statistic",
+    "TestResults",
+    "ThreeAFCMethod",
+    "TriangleMethod",
+    "TwoAFCMethod",
+    "UnspecifiedTetrad",
+]

sensopy/discrimination/discrimination.py

@@ -0,0 +1,263 @@
+"""Discrimination Test."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+import numpy.typing as npt
+from scipy.optimize import fsolve
+from scipy.stats import beta, binom
+
+if TYPE_CHECKING:
+    from .methods import DiscriminationMethod
+
+
+@dataclass(slots=True)
+class Statistic:
+    """Point estimate and confidence interval for a single test statistic."""
+
+    estimate: float
+    stderr: float
+    lower: float
+    upper: float
+
+
+@dataclass(slots=True)
+class TestResults:
+    """Full set of estimates from a discrimination test."""
+
+    pg: float
+    pc: Statistic
+    pd: Statistic
+    d_prime: Statistic
+    p_value: float
+    alpha: float
+    power: float
+
+
+@dataclass(slots=True)
+class SimulationResults:
+    """Outcome of simulating many discrimination tests."""
+
+    x: npt.NDArray[np.int_]
+    p_values: npt.NDArray[np.float64]
+    alpha: float
+    power: float
+
+
+class DiscriminationTest:
+    """Difference and equivalence tests for a single sensory discrimination method.
+
+    Implements the one-tailed difference test (H1: P_c > P_c0) and the one-tailed
+    equivalence test (H1: P_c < P_c0) described in Bi (2015, Chapters 4-5).
+
+    The test produces estimates of P_c, p_d, and d' together with their standard
+    errors and confidence limits derived from the binomial model and the delta method
+    (Bi, 2015, §2.3).
+    """
+
+    def __init__(self, method: DiscriminationMethod) -> None:
+        """Initialize a discrimination test.
+
+        Args:
+            method: The sensory discrimination method to use.
+        """
+        self.method = method
+
+    def limits(
+        self,
+        x: int,
+        n: int,
+        pc: float,
+        pd: float,
+        pg: float,
+        d_prime: float,
+        alpha: float,
+    ) -> tuple[Statistic, Statistic, Statistic]:
+        """Compute point estimates, standard errors, and confidence limits.
+
+        Standard errors for P_c and p_d use the binomial formula. The standard
+        error for d' is obtained via the delta method (Bi, 2015, §2.3):
+
+            SE(d') = SE(P_c) / f'(d')
+
+        where f'(d') is the derivative of the psychometric function, approximated
+        here by a central finite difference. Confidence limits for P_c use the
+        exact beta distribution (Clopper-Pearson) interval.
+
+        Args:
+            x: Number of correct responses.
+            n: Number of panelists (trials).
+            pc: Observed proportion correct P_c = x / n.
+            pd: Observed proportion of discriminators p_d.
+            pg: Guessing probability P_g for the method.
+            d_prime: Estimated Thurstonian distance d'.
+            alpha: Significance level (1 - confidence level).
+
+        Returns:
+            A tuple of (pc_stat, pd_stat, d_prime_stat), each a Statistic
+            namedtuple with fields (estimate, stderr, lower, upper).
+        """
+        pc_err = np.sqrt(pc * (1 - pc) / n)
+        pd_err = pc_err / (1 - pg)
+        dx = 1e-6
+        f = self.method.psychometric_function
+        der = (f(d_prime + dx) - f(d_prime - dx)) / (2 * dx)
+        d_prime_err = pc_err / der
+
+        # Lower limits
+        pc_lower = max(beta.ppf(alpha / 2, x, n - x + 1), pg)
+        pd_lower = (pc_lower - pg) / (1 - pg)
+        d_prime_lower = fsolve(lambda d: self.method.psychometric_function(d) - pc_lower, 1.0)[0]  # type: ignore[arg-type,misc]  # ty:ignore[invalid-argument-type]
+
+        # Upper limits
+        pc_upper = min(beta.ppf(1 - alpha / 2, x + 1, n - x), 1.0)
+        pd_upper = (pc_upper - pg) / (1 - pg)
+        d_prime_upper = fsolve(lambda d: self.method.psychometric_function(d) - pc_upper, 1.0)[0]  # type: ignore[arg-type,misc]  # ty:ignore[invalid-argument-type]
+
+        return (
+            Statistic(pc, pc_err, pc_lower, pc_upper),
+            Statistic(pd, pd_err, pd_lower, pd_upper),
+            Statistic(d_prime, d_prime_err, d_prime_lower, d_prime_upper),
+        )
+
+    def difference(
+        self,
+        x: int,
+        n: int,
+        pd0: float = 0,
+        conf_level: float = 0.95,
+    ) -> TestResults:
+        """One-tailed difference test (Bi, 2015, Chapter 4).
+
+        Tests whether the sensory difference exceeds a specified threshold pd0:
+
+            H0: p_d ≤ pd0  (i.e., P_c ≤ P_c0)
+            H1: p_d > pd0  (i.e., P_c > P_c0)
+
+        where P_c0 = P_g + (1 - P_g) · pd0.
+
+        Args:
+            x: Number of correct responses.
+            n: Number of panelists (trials).
+            pd0: Null-hypothesis proportion of discriminators (default 0).
+            conf_level: Confidence level for the interval estimates (default 0.95).
+
+        Returns:
+            TestResults with pg, pc, pd, d_prime (each a Statistic), p_value,
+            alpha, and power.
+        """
+        alpha = 1 - conf_level
+
+        pg = self.method.guessing
+        pc = x / n
+        pd = (pc - pg) / (1 - pg)
+        d_prime = fsolve(lambda d: self.method.psychometric_function(d) - pc, 1.0)[0]  # type: ignore[arg-type,misc]  # ty:ignore[invalid-argument-type]
+
+        def stats(x: int, n: int, pc: float, pg: float, alpha: float) -> tuple[float, float]:
+            pc0 = pg + (1 - pg) * pd0
+            p_value = 1 - binom.cdf(x - 1, n, pc0)
+            xcrit = binom.ppf(1 - alpha, n, pc0) + 1
+            power = 1 - binom.cdf(xcrit - 1, n, pc)
+            return p_value, power
+
+        p_value, power = stats(x, n, pc, pg, alpha)
+        pc_stats, pd_stats, d_prime_stats = self.limits(x, n, pc, pd, pg, d_prime, alpha)
+
+        return TestResults(pg, pc_stats, pd_stats, d_prime_stats, p_value, alpha, power)
+
+    def equivalence(
+        self,
+        x: int,
+        n: int,
+        pd0: float = 0,
+        conf_level: float = 0.95,
+    ) -> TestResults:
+        """One-tailed equivalence (similarity) test (Bi, 2015, Chapter 5).
+
+        Tests whether the sensory difference is smaller than a specified threshold pd0:
+
+            H0: p_d ≥ pd0  (i.e., P_c ≥ P_c0)
+            H1: p_d < pd0  (i.e., P_c < P_c0)
+
+        where P_c0 = P_g + (1 - P_g) · pd0.
+
+        Args:
+            x: Number of correct responses.
+            n: Number of panelists (trials).
+            pd0: Null-hypothesis proportion of discriminators (default 0).
+            conf_level: Confidence level for the interval estimates (default 0.95).
+
+        Returns:
+            TestResults with pg, pc, pd, d_prime (each a Statistic), p_value,
+            alpha, and power.
+        """
+        alpha = 1 - conf_level
+
+        pg = self.method.guessing
+        pc = x / n
+        pd = (pc - pg) / (1 - pg)
+        d_prime = fsolve(lambda d: self.method.psychometric_function(d) - pc, 1.0)[0]  # type: ignore[arg-type,misc]  # ty:ignore[invalid-argument-type]
+
+        def stats(x: int, n: int, pc: float, pg: float, alpha: float) -> tuple[float, float]:
+            pc0 = pg + (1 - pg) * pd0
+            p_value = binom.cdf(x, n, pc0)
+            # Largest count whose lower-tail p-value is still <= alpha
+            xcrit = binom.ppf(alpha, n, pc0)
+            if binom.cdf(xcrit, n, pc0) > alpha:
+                xcrit -= 1
+            power = binom.cdf(xcrit, n, pc)
+            return p_value, power
+
+        p_value, power = stats(x, n, pc, pg, alpha)
+        pc_stats, pd_stats, d_prime_stats = self.limits(x, n, pc, pd, pg, d_prime, alpha)
+
+        return TestResults(pg, pc_stats, pd_stats, d_prime_stats, p_value, alpha, power)
+
+    def simulate(
+        self,
+        d: float,
+        n: int,
+        size: int = 1000,
+        *,
+        kind: Literal["difference", "equivalence"] = "difference",
+        pd0: float = 0,
+        conf_level: float = 0.95,
+        rng: np.random.Generator | int | None = None,
+    ) -> SimulationResults:
+        """Simulate repeated discrimination tests and estimate the empirical power.
+
+        Draws ``size`` experiments of ``n`` panelists with true distance ``d``, computes
+        the one-tailed exact binomial p-value of each against ``pd0``, and reports the
+        fraction that reject the null hypothesis at ``alpha = 1 - conf_level``.
+
+        Args:
+            d: True Thurstonian distance d' used to generate the data.
+            n: Number of panelists per simulated test.
+            size: Number of tests to simulate (default 1000).
+            kind: ``"difference"`` (H1: P_c > P_c0) or ``"equivalence"`` (H1: P_c < P_c0).
+            pd0: Null-hypothesis proportion of discriminators (default 0).
+            conf_level: Confidence level (default 0.95).
+            rng: A NumPy random generator, or a seed used to create one.
+
+        Returns:
+            SimulationResults with the simulated counts, p-values, alpha and power.
+
+        Raises:
+            ValueError: If ``kind`` is not recognized or ``size`` is not positive.
+        """
+        if kind not in ("difference", "equivalence"):
+            msg = "kind must be 'difference' or 'equivalence'"
+            raise ValueError(msg)
+        if size < 1:
+            msg = "size must be a positive integer"
+            raise ValueError(msg)
+
+        alpha = 1 - conf_level
+        pg = self.method.guessing
+        pc0 = pg + (1 - pg) * pd0
+        x = self.method.simulate(d, n, size=size, rng=rng)
+        p_values = 1 - binom.cdf(x - 1, n, pc0) if kind == "difference" else binom.cdf(x, n, pc0)
+        return SimulationResults(x, p_values, alpha, float(np.mean(p_values <= alpha)))

sensopy/discrimination/methods.py

@@ -0,0 +1,537 @@
+"""Discrimination methods."""
+
+from __future__ import annotations
+
+import abc
+from typing import overload
+
+import numpy as np
+import numpy.typing as npt
+import scipy.special
+from scipy.integrate import trapezoid
+from scipy.stats import norm
+
+from . import mplusn
+
+__all__ = [
+    "DUAL_PAIR",
+    "DUO_TRIO",
+    "FOUR_AFC",
+    "SPECIFIED_TETRAD",
+    "THREE_AFC",
+    "TRIANGLE",
+    "TWO_AFC",
+    "UNSPECIFIED_TETRAD",
+    "MPlusNMethod",
+    "MultipleAFCMethod",
+]
+
+
+class DiscriminationMethod(abc.ABC):
+    """A sensory discrimination method."""
+
+    @abc.abstractmethod
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function relating d' to the probability of a correct response.
+
+        Args:
+            d: Thurstonian discriminal distance d' (δ), a method-independent measure
+                of sensory difference/similarity (Bi, 2015, §2.1).
+
+        Returns:
+            Probability of a correct response P_c for the given d'.
+        """
+        ...
+
+    @property
+    @abc.abstractmethod
+    def guessing(self) -> float:
+        """Chance-level probability of a correct response when d' = 0."""
+        ...
+
+    def discriminators(self, d: float) -> float:
+        """Proportion of discriminators (p_d) for a given d'.
+
+        p_d is the proportion of the population that can reliably detect the
+        sensory difference, estimated as (P_c - P_g) / (1 - P_g), where P_g
+        is the guessing rate (Bi, 2015, §4.1).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Proportion of discriminators p_d.
+        """
+        pc = self.psychometric_function(d)
+        pg = self.guessing
+        return (pc - pg) / (1 - pg)
+
+    @overload
+    def simulate(
+        self,
+        d: float,
+        n: int,
+        size: None = None,
+        rng: np.random.Generator | int | None = None,
+    ) -> int: ...
+
+    @overload
+    def simulate(
+        self,
+        d: float,
+        n: int,
+        size: int,
+        rng: np.random.Generator | int | None = None,
+    ) -> npt.NDArray[np.int_]: ...
+
+    def simulate(
+        self,
+        d: float,
+        n: int,
+        size: int | None = None,
+        rng: np.random.Generator | int | None = None,
+    ) -> int | npt.NDArray[np.int_]:
+        """Simulate the number of correct responses in a discrimination test.
+
+        Each of the ``n`` panelists answers correctly with probability
+        P_c = ψ(d'), so the number of correct responses is distributed as
+        Binomial(n, P_c) (Bi, 2015, §2.3).
+
+        Args:
+            d: True Thurstonian discriminal distance d' (must be non-negative).
+            n: Number of panelists (trials) per simulated test.
+            size: Number of tests to simulate. If None, a single test is simulated
+                and a scalar is returned.
+            rng: A NumPy random generator, or a seed used to create one.
+
+        Returns:
+            The number of correct responses, or an array of them if ``size`` is given.
+
+        Raises:
+            ValueError: If ``d`` is negative or ``n`` is not positive.
+        """
+        if d < 0:
+            msg = "d' must be non-negative"
+            raise ValueError(msg)
+        if n < 1:
+            msg = "n must be a positive integer"
+            raise ValueError(msg)
+
+        generator = np.random.default_rng(rng)
+        pc = min(max(self.psychometric_function(d), 0.0), 1.0)
+        result = generator.binomial(n, pc, size=size)
+        return int(result) if size is None else result
+
+
+class TriangleMethod(DiscriminationMethod):
+    """Triangle (Triangular) discrimination method (Dawson and Harris 1951, Peryam 1958).
+
+    Three samples of two products, A and B, are presented to each panelist. Two of them
+    are the same. The possible sets of samples are AAB, ABA, BAA, ABB, BAB, and BBA.
+    The panelist is asked to select the odd sample and must select one even if they
+    cannot identify it (Bi, 2015, §1.5.1d).
+
+    The psychometric function is (Bi, 2015, eq. 2.2.5):
+
+        P_c = 2 ∫_0^∞ φ(x) { Φ[-√3·x + √(2/3)·δ] + Φ[-√3·x - √(2/3)·δ] } dx
+
+    Guessing probability: 1/3.
+    """
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the Triangle method (Bi, 2015, eq. 2.2.5).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c.
+        """
+        f1 = norm.pdf
+        f2 = norm.cdf
+
+        def _fi(z: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
+            x1 = -z * np.sqrt(3) + np.sqrt(2 / 3) * d
+            x2 = -z * np.sqrt(3) - np.sqrt(2 / 3) * d
+            return 2 * (f2(x1) + f2(x2)) * f1(z)  # type: ignore[no-any-return]
+
+        x = np.linspace(0, 200, 10000)
+        y = _fi(x)
+        return trapezoid(y, x)  # type: ignore[no-any-return]
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the Triangle method (1/3)."""
+        return 1 / 3
+
+
+class TwoAFCMethod(DiscriminationMethod):
+    """Two-Alternative Forced Choice (2-AFC) method (Green and Swets 1966).
+
+    Also called the paired comparison method (Dawson and Harris 1951, Peryam 1958).
+    The panelist receives a pair of coded samples, A and B, for comparison on the basis
+    of a specified sensory characteristic. The possible pairs are AB and BA. The panelist
+    selects the sample with the strongest (or weakest) characteristic and must choose
+    even if they cannot detect a difference (Bi, 2015, §1.5.1a).
+
+    The psychometric function is (Bi, 2015, eq. 2.2.1):
+
+        P_c = Φ(δ / √2)
+
+    Guessing probability: 1/2.
+    """
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the 2-AFC method (Bi, 2015, eq. 2.2.1).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c.
+        """
+        return norm.cdf(d / np.sqrt(2))  # type: ignore[no-any-return]
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the 2-AFC method (1/2)."""
+        return 1 / 2
+
+
+class ThreeAFCMethod(DiscriminationMethod):
+    """Three-Alternative Forced Choice (3-AFC) method (Green and Swets 1966).
+
+    Three samples of two products, A and B, are presented to each panelist. Two of them
+    are the same. The possible sets of samples are AAB, ABA, BAA or ABB, BAB, BBA.
+    The panelist selects the sample with the strongest or weakest characteristic and must
+    choose even if they cannot identify it (Bi, 2015, §1.5.1b).
+
+    The psychometric function is (Bi, 2015, eq. 2.2.2):
+
+        P_c = ∫_{-∞}^{∞} Φ²(u) φ(u - δ) du
+
+    Guessing probability: 1/3.
+    """
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the 3-AFC method (Bi, 2015, eq. 2.2.2).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c.
+        """
+
+        def _fi(z: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
+            return (norm.cdf(z) ** 2) * norm.pdf(z - d)
+
+        x = np.linspace(-100, 100, 10000)
+        y = _fi(x)
+        return trapezoid(y, x)  # type: ignore[no-any-return]
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the 3-AFC method (1/3)."""
+        return 1 / 3
+
+
+class FourAFCMethod(DiscriminationMethod):
+    """Four-Alternative Forced Choice (4-AFC) method (Swets 1959).
+
+    Four samples of two products, A and B, are presented to each panelist. Three of them
+    are the same. The possible sets of samples are AAAB, AABA, ABAA, BAAA or BBBA,
+    BBAB, BABB, ABBB. The panelist selects the sample with the strongest or weakest
+    characteristic and must choose even if they cannot identify it (Bi, 2015, §1.5.1c).
+
+    The psychometric function is (Bi, 2015, eq. 2.2.3):
+
+        P_c = ∫_{-∞}^{∞} Φ³(u) φ(u - δ) du
+
+    Guessing probability: 1/4.
+    """
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the 4-AFC method (Bi, 2015, eq. 2.2.3).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c.
+        """
+
+        def _fi(z: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
+            return (norm.cdf(z) ** 3) * norm.pdf(z - d)
+
+        x = np.linspace(-100, 100, 10000)
+        y = _fi(x)
+        return trapezoid(y, x)  # type: ignore[no-any-return]
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the 4-AFC method (1/4)."""
+        return 1 / 4
+
+
+class MultipleAFCMethod(DiscriminationMethod):
+    """m-Alternative Forced Choice (m-AFC) method.
+
+    Generalisation of the AFC family. m samples are presented; (m - 1) are from
+    product A and one from product B. The panelist selects the sample with the
+    strongest (or weakest) characteristic (Bi, 2015, §1.5.1).
+
+    The psychometric function is (Bi, 2015, eq. 2.2.3 generalised):
+
+        P_c = ∫_{-∞}^{∞} Φ^(m-1)(u) φ(u - δ) du
+
+    Guessing probability: 1/m.
+    """
+
+    def __init__(self, m: int) -> None:
+        """Initialize an m-AFC discrimination method.
+
+        Args:
+            m: Number of alternatives (must be ≥ 2).
+        """
+        self.m = m
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the m-AFC method (Bi, 2015, eq. 2.2.3 generalised).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c.
+        """
+
+        def _fi(z: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
+            return (norm.cdf(z) ** (self.m - 1)) * norm.pdf(z - d)
+
+        x = np.linspace(-100, 100, 10000)
+        y = _fi(x)
+        return trapezoid(y, x)  # type: ignore[no-any-return]
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the m-AFC method (1/m)."""
+        return 1 / self.m
+
+
+class SpecifiedTetradMethod(DiscriminationMethod):
+    """Specified Tetrad method (Wood 1949).
+
+    Four stimuli — two of A and two of B — are presented. A and B are confusable and
+    vary in the relative strengths of their sensory attributes. Panelists are told that
+    there are two pairs of putatively identical stimuli and must indicate the two stimuli
+    of the specified product (A or B) (Bi, 2015, §1.5.1g).
+
+    The psychometric function is (Bi, 2015, eq. 2.2.11):
+
+        P_c = 1 - 2 ∫_{-∞}^{∞} φ(x) Φ(x) { 2Φ(x - δ) - [Φ(x - δ)]² } dx
+
+    Guessing probability: 1/6.
+    """
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the Specified Tetrad method (Bi, 2015, eq. 2.2.11).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c.
+        """
+        f1 = norm.pdf
+        f2 = norm.cdf
+
+        def _fi(z: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
+            return 2 * (f1(z) * f2(z) * (2 * f2(z - d) - f2(z - d) ** 2))
+
+        x = np.linspace(-100, 100, 10000)
+        y = _fi(x)
+        i = trapezoid(y, x)
+
+        return 1 - i  # type: ignore[no-any-return]
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the Specified Tetrad method (1/6)."""
+        return 1 / 6
+
+
+class UnspecifiedTetrad(DiscriminationMethod):
+    """Unspecified Tetrad method (Lockhart 1951).
+
+    Four stimuli — two of A and two of B — are presented. A and B are confusable and
+    vary in the relative strengths of their sensory attributes. Panelists are told that
+    there are two pairs of putatively identical stimuli and must sort them into their
+    pairs, without being told which product to identify (Bi, 2015, §1.5.1f).
+
+    The psychometric function is (Bi, 2015, eq. 2.2.8):
+
+        P_c = 1 - 2 ∫_{-∞}^{∞} φ(x) { 2Φ(x)Φ(x - δ) - [Φ(x - δ)]² } dx
+
+    Guessing probability: 1/3.
+    """
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the Unspecified Tetrad method (Bi, 2015, eq. 2.2.8).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c.
+        """
+        f1 = norm.pdf
+        f2 = norm.cdf
+
+        def _fi(z: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
+            return 2 * (f1(z) * (2 * f2(z) * f2(z - d) - f2(z - d) ** 2))
+
+        x = np.linspace(-100, 100, 10000)
+        y = _fi(x)
+        i = trapezoid(y, x)
+
+        return 1 - i  # type: ignore[no-any-return]
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the Unspecified Tetrad method (1/3)."""
+        return 1 / 3
+
+
+class DualPairMethod(DiscriminationMethod):
+    """Dual Pair (4IAX) method (Macmillan et al. 1977).
+
+    Two pairs of samples are presented simultaneously to the panelist. One pair is
+    composed of samples of the same stimulus (AA or BB); the other is composed of
+    samples of different stimuli (AB or BA). The panelist selects the most different
+    pair of the two (Bi, 2015, §1.5.1h).
+
+    The psychometric function is (Bi, 2015, eq. 2.2.12):
+
+        P_c = [Φ(δ/2)]² + [Φ(-δ/2)]²
+
+    Guessing probability: 1/2.
+    """
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the Dual Pair method (Bi, 2015, eq. 2.2.12).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c.
+        """
+        return norm.cdf(d / 2) ** 2 + norm.cdf(-d / 2) ** 2
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the Dual Pair method (1/2)."""
+        return 1 / 2
+
+
+class DuoTrioMethod(DiscriminationMethod):
+    """Duo-Trio method (Dawson and Harris 1951, Peryam 1958).
+
+    Three samples of two products, A and B, are presented to each panelist. Two of them
+    are the same. The possible sets of samples are A:AB, A:BA, B:AB, and B:BA. The first
+    sample is labelled the "control." The panelist selects which of the two test samples
+    matches the control and must choose even if they cannot identify the match
+    (Bi, 2015, §1.5.1e).
+
+    The psychometric function is (Bi, 2015, eq. 2.2.4):
+
+        P_c = 1 - Φ(δ/√2) - Φ(δ/√6) + 2 Φ(δ/√2) Φ(δ/√6)
+
+    Guessing probability: 1/2.
+    """
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the Duo-Trio method (Bi, 2015, eq. 2.2.4).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c.
+        """
+        x1 = d / np.sqrt(2)
+        x2 = d / np.sqrt(6)
+        return 1 - norm.cdf(x1) - norm.cdf(x2) + 2 * norm.cdf(x1) * norm.cdf(x2)  # type: ignore[no-any-return]
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the Duo-Trio method (1/2)."""
+        return 1 / 2
+
+
+class MPlusNMethod(DiscriminationMethod):
+    """M + N discrimination method (Lockhart 1951).
+
+    M + N samples are presented: M samples of product A and N samples of product B.
+    The panelist divides them into two groups of A and B. There are two versions:
+    specified (panelist is told which group is A) and unspecified (Bi, 2015, §1.5.1i).
+
+    This is a generalisation of many forced-choice methods, including m-AFC, Triangle,
+    and both Tetrad variants. For small M and N a binomial model applies; for larger
+    M and N (M = N > 3) a single set of samples can reach statistical significance
+    under a hypergeometric model (Bi, 2015, §2.5).
+
+    The psychometric function is estimated by Monte Carlo simulation (Bi, 2015, §2.5).
+
+    Guessing probability: 1/C(M+N, N) for specified or M > N; 2/C(M+N, N) otherwise.
+    """
+
+    def __init__(self, m: int, n: int, specified: bool = False, *, seed: int | None = None) -> None:
+        """Initialize an M + N discrimination method.
+
+        Args:
+            m: Number of samples from product A (must be ≥ n).
+            n: Number of samples from product B.
+            specified: If True, panelists are told which group is product A (specified
+                version); otherwise the unspecified version is used.
+            seed: Seed for the random number generator used in the Monte Carlo
+                simulation of the psychometric function. Pass an integer for
+                reproducible results; ``None`` (default) uses an unpredictable seed.
+        """
+        self.m = m
+        self.n = n
+        self.specified = specified
+        self.psy_func = mplusn.mplusn_mc(m, n, specified=specified, seed=seed)
+
+    def psychometric_function(self, d: float) -> float:
+        """Psychometric function for the M + N method (Monte Carlo estimate).
+
+        Args:
+            d: Thurstonian discriminal distance d'.
+
+        Returns:
+            Probability of a correct response P_c (interpolated from simulation).
+        """
+        return self.psy_func(d)
+
+    @property
+    def guessing(self) -> float:
+        """Chance-level probability for the M + N method.
+
+        Returns 1/C(M+N, N) for the specified version or when M > N, and
+        2/C(M+N, N) for the unspecified version when M = N (Bi, 2015, §2.5).
+        """
+        if self.m > self.n or self.specified:
+            return float(1 / scipy.special.binom(self.m + self.n, self.n))
+        return float(2 / scipy.special.binom(self.m + self.n, self.n))
+
+
+TRIANGLE = TriangleMethod()
+TWO_AFC = TwoAFCMethod()
+THREE_AFC = ThreeAFCMethod()
+FOUR_AFC = FourAFCMethod()
+SPECIFIED_TETRAD = SpecifiedTetradMethod()
+UNSPECIFIED_TETRAD = UnspecifiedTetrad()
+DUAL_PAIR = DualPairMethod()
+DUO_TRIO = DuoTrioMethod()

sensopy/discrimination/mplusn.py

@@ -0,0 +1,89 @@
+"""M plus N generation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import numpy.typing as npt
+from scipy import interpolate
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+SAMPLE_SIZE = 100000
+
+
+def mplusn_mc(
+    m: int,
+    n: int,
+    specified: bool = False,
+    max_delta: float = 10,
+    steps: int = 300,
+    seed: int | None = None,
+    sample_size: int = SAMPLE_SIZE,
+) -> Callable[[float], float]:
+    """Monte Carlo simulation for M + N method.
+
+    Args:
+        m: TODO.
+        n: TODO.
+        specified: TODO.
+        max_delta: TODO.
+        steps: TODO.
+        seed: TODO.
+        sample_size: TODO.
+
+    Returns:
+        TODO.
+
+    Raises:
+        ValueError: If `m` is smaller than `n`.
+    """
+    if m < n:
+        raise ValueError("Invalid combination of parameters. M >= N expected.")
+
+    delta = np.linspace(0, max_delta, steps)
+    prop = []
+    k = m - n
+
+    def _func1(a: npt.NDArray[np.float64], b: npt.NDArray[np.float64]) -> float:
+        return np.mean(a[-1] < b[0])  # type: ignore[no-any-return]
+
+    def _func2(a: npt.NDArray[np.float64], b: npt.NDArray[np.float64]) -> float:
+        cond1 = a[-1] < b[0]
+        cond2 = a[0] > b[-1]
+        return np.mean(cond1 | cond2)  # type: ignore[no-any-return]
+
+    def _func3(a: npt.NDArray[np.float64], b: npt.NDArray[np.float64]) -> float:
+        cond1 = ((b[k] - b[k - 1]) < (b[0] - a[n - 1])) & (a[-1] < b[0])
+        cond2 = ((b[n] - b[n - 1]) < (a[0] - b[m - 1])) & (a[0] > b[-1])
+        return np.mean(cond1 | cond2)  # type: ignore[no-any-return]
+
+    # Specified test
+    if specified:
+        p = _func1
+    # Test with M = N
+    elif k == 0:
+        p = _func2
+    # Test with M > N
+    else:
+        p = _func3
+
+    # Seed the random number generator
+    rng = np.random.default_rng(seed=seed)
+    for d in delta:
+        # Samples from A ~ N(0,1)
+        a = rng.standard_normal(size=(n, sample_size))
+
+        # Samples from B ~ N(d,1)
+        b = rng.standard_normal(size=(m, sample_size)) + d
+
+        # Sort corresponding n-tuples
+        a.sort(axis=0)
+        b.sort(axis=0)
+        pc = p(a, b)
+
+        prop.append(pc)
+
+    return interpolate.interp1d(delta, prop)  # type: ignore[return-value] # ty: ignore[invalid-return-type]

sensopy-0.0.1.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: sensopy
+Version: 0.0.1
+Summary: Python library for the design and analysis of sensory discrimination tests.
+Project-URL: Issue Tracker, https://github.com/edgarrmondragon/SensoPy/issues
+Author-email: Edgar Ramírez-Mondragón <edgarrm358@gmail.com>
+Maintainer-email: Edgar Ramírez-Mondragón <edgarrm358@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: discrimination,sensory,triangle
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: numpy>=2.2
+Requires-Dist: scipy>=1.15
+Description-Content-Type: text/markdown
+
+# SensoPy
+
+[![SPEC 0](https://img.shields.io/badge/SPEC-0-green)](https://scientific-python.org/specs/spec-0000/)
+[![Tests](https://github.com/edgarrmondragon/SensoPy/actions/workflows/tests.yml/badge.svg)](https://github.com/edgarrmondragon/SensoPy/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/edgarrmondragon/SensoPy/branch/main/graph/badge.svg?token=k3m3CmIACa)](https://codecov.io/gh/edgarrmondragon/SensoPy)
+
+Python library for the design and analysis of sensory discrimination tests. I have plans to make this a full-fledged sensory data analysis library by including all common standard techniques (Preference Mapping, Penalty Analysis, DOE, etc.)
+
+## Installation
+
+```shell
+pip install SensoPy
+```
+
+## Usage
+
+### Difference test
+
+One-tailed test of H0: p_d = 0 (no difference) against H1: p_d > 0 (a difference
+exists). 19 correct responses out of 30 panelists using the Triangle method:
+
+```python
+from sensopy import DiscriminationTest
+from sensopy.discrimination import TRIANGLE
+
+test = DiscriminationTest(TRIANGLE)
+result = test.difference(19, 30)
+
+print(f"d'      = {result.d_prime.estimate:.4f}  [{result.d_prime.lower:.4f}, {result.d_prime.upper:.4f}]")
+print(f"p_d     = {result.pd.estimate:.4f}  [{result.pd.lower:.4f}, {result.pd.upper:.4f}]")
+print(f"p-value = {result.p_value:.4f}")
+```
+
+```
+d'      = 2.1462  [1.1262, 3.1336]
+p_d     = 0.4500  [0.1578, 0.7011]
+p-value = 0.0007
+```
+
+- **d' = 2.15** (95% CI: [1.13, 3.13]): estimated Thurstonian discriminal distance,
+    a method-independent measure of the sensory difference between the two products.
+- **p_d = 0.45** (95% CI: [0.16, 0.70]): an estimated 45% of the panel can reliably
+    detect the difference.
+- **p-value = 0.0007**: strong evidence against H0; the products are perceptibly
+    different at any conventional significance level.
+
+### Equivalence test
+
+One-tailed test of H0: p_d >= 0.30 against H1: p_d < 0.30 (the products are
+sensorially similar). `pd0 = 0.30` sets the equivalence threshold: the maximum
+proportion of discriminators we are willing to tolerate and still call the products
+equivalent. 16 correct out of 30 panelists using the 2-AFC method:
+
+```python
+from sensopy import DiscriminationTest
+from sensopy.discrimination import TWO_AFC
+
+test = DiscriminationTest(TWO_AFC)
+result = test.equivalence(16, 30, pd0=0.30)
+
+print(f"d'      = {result.d_prime.estimate:.4f}  [{result.d_prime.lower:.4f}, {result.d_prime.upper:.4f}]")
+print(f"p_d     = {result.pd.estimate:.4f}  [{result.pd.lower:.4f}, {result.pd.upper:.4f}]")
+print(f"p-value = {result.p_value:.4f}")
+```
+
+```
+d'      = 0.1183  [0.0000, 0.8099]
+p_d     = 0.0667  [0.0000, 0.4332]
+p-value = 0.1263
+```
+
+- **d' = 0.12** (95% CI: [0.00, 0.81]): small estimated sensory distance, consistent
+    with near-identical products.
+- **p_d = 0.07** (95% CI: [0.00, 0.43]): only ~7% of the panel estimated to reliably
+    discriminate the products.
+- **p-value = 0.13**: insufficient evidence to conclude equivalence at α = 0.05 with
+    pd0 = 0.30 (i.e., we cannot rule out that ≥ 30% of consumers can detect the
+    difference); a larger panel would be needed to meet that threshold.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md).
+
+## Citing
+
+If you use SensoPy in your work, please cite it using [CITATION.cff](CITATION.cff);
+GitHub's "Cite this repository" button exports it as APA or BibTeX.
+
+## Credits
+
+<ul>
+  <li>Edgar Ramírez Mondragón</li>
+</ul>
+
+## References
+
+<ol>
+  <li>Bi, J. 2015. Sensory Discrimination Tests and Measurements. <em>Sensometrics in Sensory Evaluation</em>. Wiley Blackwell, Richmond, Virginia, USA.</li>
+</ol>

sensopy-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+sensopy/__init__.py,sha256=jTTg4CPauQ6xAZO8JdNXytNl0GITgFcqe9_VE4zGuew,250
+sensopy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sensopy/discrimination/__init__.py,sha256=RjGFelbAZ12c7_EDNB89o-XrJ39oFey4M3Ue_e8Sozg,994
+sensopy/discrimination/discrimination.py,sha256=uSoTl595UdQMY67H1N6Sn1KP_tFwiHdZq9sRXj1fU9s,9412
+sensopy/discrimination/methods.py,sha256=SC4msqjxVh1kTSBrvTX1ZqwNYRk2vU5R0XvDFDUPYYo,17897
+sensopy/discrimination/mplusn.py,sha256=RTp21kCa4olZpQjP2W2rjVhn0cB7Tok3cCzjaoyG__g,2298
+sensopy-0.0.1.dist-info/METADATA,sha256=CgY1Y4iZMsY0JBPMN1YQ0RIsrRfszM4oLRS1rLszTVc,4801
+sensopy-0.0.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+sensopy-0.0.1.dist-info/licenses/LICENSE,sha256=gLnGgBQCs6EYHnKpg7Cs1mH8XJEZdL3khPhCjZSR8Ec,1083
+sensopy-0.0.1.dist-info/RECORD,,

sensopy-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sensopy-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019, Edgar Ramírez Mondragón
+
+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.