abtestwise 0.1.0__py3-none-any.whl

abtestwise/__init__.py

@@ -0,0 +1,14 @@
+"""abtestwise: a lightweight toolkit for binary A/B experiment analysis.
+
+Version 0.1 combines frequentist and Bayesian summaries for binary proportions
+using aggregate count data.
+"""
+
+from __future__ import annotations
+
+from .binary import BinaryABTest
+from .result import BinaryABResult
+
+__version__ = "0.1.0"
+
+__all__ = ["BinaryABTest", "BinaryABResult", "__version__"]

abtestwise/bayesian.py

@@ -0,0 +1,77 @@
+"""Bayesian analysis: beta-binomial posterior simulation.
+
+For a binary metric with a Beta prior, the posterior for each group's true
+success rate is conjugate and also Beta:
+
+posterior = Beta(prior_alpha + successes, prior_beta + failures)
+
+We draw samples from each group's posterior, form the lift distribution
+(Treatment B - Control A), and summarize it using NumPy operations.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def posterior_samples(
+    successes: int,
+    total: int,
+    prior_alpha: float,
+    prior_beta: float,
+    n_simulations: int,
+    rng: np.random.Generator,
+) -> np.ndarray:
+    """"Draw posterior samples of a group's true success rate from its Beta posterior."""
+    failures = total - successes
+    alpha = prior_alpha + successes
+    beta = prior_beta + failures
+    return rng.beta(alpha, beta, size=n_simulations)
+
+
+def simulate_lift_samples(
+    control_successes: int,
+    control_total: int,
+    treatment_successes: int,
+    treatment_total: int,
+    prior_alpha: float,
+    prior_beta: float,
+    n_simulations: int,
+    rng: np.random.Generator,
+) -> np.ndarray:
+    """Return posterior samples of the lift (treatment rate - control rate)."""
+    control = posterior_samples(
+        control_successes, control_total, prior_alpha, prior_beta, n_simulations, rng
+    )
+    treatment = posterior_samples(
+        treatment_successes,
+        treatment_total,
+        prior_alpha,
+        prior_beta,
+        n_simulations,
+        rng,
+    )
+    return treatment - control
+
+
+def credible_interval_bounds(
+    lift_samples: np.ndarray, credible_interval: float
+) -> tuple[float, float]:
+    """Equal-tailed credible interval for the lift at the given level.
+
+    For a 0.95 interval this returns the 2.5th and 97.5th percentiles.
+    """
+    tail = (1.0 - credible_interval) / 2.0
+    lower = float(np.quantile(lift_samples, tail))
+    upper = float(np.quantile(lift_samples, 1.0 - tail))
+    return lower, upper
+
+
+def expected_loss_treatment(lift_samples: np.ndarray) -> float:
+    """Expected loss from choosing treatment: mean(max(-lift, 0))."""
+    return float(np.mean(np.maximum(-lift_samples, 0.0)))
+
+
+def expected_loss_control(lift_samples: np.ndarray) -> float:
+    """Expected loss from choosing control: mean(max(lift, 0))."""
+    return float(np.mean(np.maximum(lift_samples, 0.0)))

abtestwise/binary.py

@@ -0,0 +1,143 @@
+"""Run binary A/B tests from aggregate count data.
+
+This module validates inputs, sets up the random number generator so results are
+reproducible from a seed, and combines the frequentist and Bayesian helpers to
+build a :class:BinaryABResult.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+from . import bayesian, frequentist, validation
+from .result import BinaryABResult
+
+
+@dataclass(frozen=True)
+class BinaryABTest:
+    """A binary A/B test using aggregate success and total counts."""
+
+    control_successes: int
+    control_total: int
+    treatment_successes: int
+    treatment_total: int
+    prior_alpha: float
+    prior_beta: float
+    n_simulations: int
+    credible_interval: float
+    seed: int | None
+
+    @classmethod
+    def from_counts(
+        cls,
+        control_successes: int,
+        control_total: int,
+        treatment_successes: int,
+        treatment_total: int,
+        *,
+        prior_alpha: float = 1.0,
+        prior_beta: float = 1.0,
+        n_simulations: int = 100_000,
+        credible_interval: float = 0.95,
+        seed: int | None = None,
+    ) -> "BinaryABTest":
+        """Create a binary A/B test from aggregate counts.
+
+        The four count inputs can be positional. All other settings have to be names.
+        The default prior is Beta(1, 1).
+        """
+        validation.validate_count("control_successes", control_successes)
+        validation.validate_total("control_total", control_total)
+        validation.validate_count("treatment_successes", treatment_successes)
+        validation.validate_total("treatment_total", treatment_total)
+        validation.validate_successes_le_total(
+            "control_successes", control_successes, "control_total", control_total
+        )
+        validation.validate_successes_le_total(
+            "treatment_successes",
+            treatment_successes,
+            "treatment_total",
+            treatment_total,
+        )
+        validation.validate_prior("prior_alpha", prior_alpha)
+        validation.validate_prior("prior_beta", prior_beta)
+        validation.validate_n_simulations(n_simulations)
+        validation.validate_credible_interval(credible_interval)
+        validation.validate_seed(seed)
+
+        return cls(
+            control_successes=control_successes,
+            control_total=control_total,
+            treatment_successes=treatment_successes,
+            treatment_total=treatment_total,
+            prior_alpha=float(prior_alpha),
+            prior_beta=float(prior_beta),
+            n_simulations=n_simulations,
+            credible_interval=credible_interval,
+            seed=seed,
+        )
+
+    def run(self) -> BinaryABResult:
+        """Run the frequentist and Bayesian analyses and return the result."""
+        control_rate = self.control_successes / self.control_total
+        treatment_rate = self.treatment_successes / self.treatment_total
+        absolute_lift = treatment_rate - control_rate
+
+        # Relative lift is undefined when the control rate is zero.
+        relative_lift = (
+            absolute_lift / control_rate if control_rate != 0 else math.nan
+        )
+
+        # --- Frequentist ---
+        z_statistic, p_value = frequentist.two_proportion_z_test(
+            self.control_successes,
+            self.control_total,
+            self.treatment_successes,
+            self.treatment_total,
+        )
+
+        # --- Bayesian ---
+        rng = np.random.default_rng(self.seed)
+        lift_samples = bayesian.simulate_lift_samples(
+            self.control_successes,
+            self.control_total,
+            self.treatment_successes,
+            self.treatment_total,
+            self.prior_alpha,
+            self.prior_beta,
+            self.n_simulations,
+            rng,
+        )
+
+        lower, upper = bayesian.credible_interval_bounds(
+            lift_samples, self.credible_interval
+        )
+
+        return BinaryABResult(
+            control_successes=self.control_successes,
+            control_total=self.control_total,
+            treatment_successes=self.treatment_successes,
+            treatment_total=self.treatment_total,
+            prior_alpha=self.prior_alpha,
+            prior_beta=self.prior_beta,
+            n_simulations=self.n_simulations,
+            credible_interval=self.credible_interval,
+            seed=self.seed,
+            control_rate=control_rate,
+            treatment_rate=treatment_rate,
+            absolute_lift=absolute_lift,
+            relative_lift=relative_lift,
+            z_statistic=z_statistic,
+            p_value=p_value,
+            posterior_mean_lift=float(np.mean(lift_samples)),
+            posterior_median_lift=float(np.median(lift_samples)),
+            prob_treatment_better=float(np.mean(lift_samples > 0)),
+            prob_control_better=float(np.mean(lift_samples < 0)),
+            credible_interval_bounds=(lower, upper),
+            expected_loss_treatment=bayesian.expected_loss_treatment(lift_samples),
+            expected_loss_control=bayesian.expected_loss_control(lift_samples),
+            lift_samples=lift_samples,
+        )

abtestwise/frequentist.py

@@ -0,0 +1,48 @@
+"""Frequentist two-sided pooled two-proportion z-test."""
+
+from __future__ import annotations
+
+import math
+
+from scipy.stats import norm
+
+
+def two_proportion_z_test(
+    control_successes: int,
+    control_total: int,
+    treatment_successes: int,
+    treatment_total: int,
+) -> tuple[float, float]:
+    """Run a two-sided pooled two-proportion z-test.
+
+    Returns ``(z_statistic, p_value)``.
+
+    The pooled estimate combines both arms under the null hypothesis that the
+    two proportions are equal:
+
+        p_pool = (x_c + x_t) / (n_c + n_t)
+        se     = sqrt(p_pool * (1 - p_pool) * (1/n_c + 1/n_t))
+        z      = (rate_t - rate_c) / se
+        p      = 2 * (1 - Phi(|z|))
+
+    If the standard error is zero, then return ``(0.0, 1.0)`` to avoid dividing by zero.
+    """
+    control_rate = control_successes / control_total
+    treatment_rate = treatment_successes / treatment_total
+
+    pooled_rate = (control_successes + treatment_successes) / (
+        control_total + treatment_total
+    )
+    standard_error = math.sqrt(
+        pooled_rate
+        * (1.0 - pooled_rate)
+        * (1.0 / control_total + 1.0 / treatment_total)
+    )
+
+    if standard_error == 0.0:
+        return 0.0, 1.0
+
+    z_statistic = (treatment_rate - control_rate) / standard_error
+    p_value = 2.0 * (1.0 - norm.cdf(abs(z_statistic)))
+
+    return float(z_statistic), float(p_value)

abtestwise/plotting.py

@@ -0,0 +1,143 @@
+"""Plotting for binary A/B test results.
+
+Lift is always Treatment B - Control A. Plots show the lift in percentage points,
+so a raw lift of 0.025 will be displayed as +2.5 percentage points.
+
+These functions return matplotlib Axes objects. Note that they do not call plt.show()
+or save files automatically.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from matplotlib.axes import Axes
+
+# Raw lift is a proportion difference; multiply by 100 to get percentage points.
+_PCT_POINTS = 100.0
+
+
+def plot_lift_distribution(
+    lift_samples: np.ndarray,
+    median_lift: float,
+    credible_interval_bounds: tuple[float, float],
+    credible_interval: float,
+    *,
+    ax: "Axes | None" = None,
+    bins: int = 50,
+    density: bool = True,
+    title: str | None = "Posterior Distribution of Lift",
+) -> "Axes":
+    """Histogram of the posterior lift distribution (Treatment B - Control A).
+
+    Marks zero, the posterior median, and the credible-interval bounds. All
+    lift values are shown in percentage points.
+    """
+    import matplotlib.pyplot as plt
+
+    if ax is None:
+        _, ax = plt.subplots(figsize=(8, 5))
+
+    samples_pp = np.asarray(lift_samples) * _PCT_POINTS
+    median_pp = median_lift * _PCT_POINTS
+    lower_pp = credible_interval_bounds[0] * _PCT_POINTS
+    upper_pp = credible_interval_bounds[1] * _PCT_POINTS
+    ci_pct = credible_interval * 100
+
+    ax.hist(
+        samples_pp,
+        bins=bins,
+        density=density,
+        color="#4C72B0",
+        alpha=0.7,
+        edgecolor="white",
+        linewidth=0.5,
+    )
+
+    # Zero reference: where Treatment B and Control A are equal.
+    ax.axvline(0.0, color="#444444", linestyle="--", linewidth=1.5, label="No difference")
+    # Posterior median lift.
+    ax.axvline(
+        median_pp,
+        color="#C44E52",
+        linestyle="-",
+        linewidth=2.0,
+        label=f"Median {median_pp:+.2f} pp",
+    )
+    # Credible interval bounds.
+    ax.axvline(
+        lower_pp,
+        color="#55A868",
+        linestyle=":",
+        linewidth=1.8,
+        label=f"{ci_pct:g}% CI [{lower_pp:+.2f}, {upper_pp:+.2f}] pp",
+    )
+    ax.axvline(upper_pp, color="#55A868", linestyle=":", linewidth=1.8)
+
+    ax.set_xlabel("Lift: Treatment B - Control A (percentage points)")
+    ax.set_ylabel("Density" if density else "Frequency")
+    if title is not None:
+        ax.set_title(title)
+    ax.legend(loc="best", frameon=True, fontsize=9)
+    ax.margins(x=0.02)
+
+    return ax
+
+
+def plot_probability_bar(
+    prob_treatment_better: float,
+    prob_control_better: float,
+    *,
+    ax: "Axes | None" = None,
+    title: str | None = "Posterior Probability of Being Better",
+) -> "Axes":
+    """Two-bar chart comparing P(Treatment B better) vs P(Control A better)."""
+    import matplotlib.pyplot as plt
+
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6, 5))
+
+    labels = ["Treatment B better", "Control A better"]
+    values = [prob_treatment_better, prob_control_better]
+    colors = ["#4C72B0", "#C44E52"]
+
+    bars = ax.bar(labels, values, color=colors, width=0.6, edgecolor="white")
+
+    # Percentage labels. For tall bars (near the top boundary) we place the
+    # label *inside* the bar in white so it does not overlap the chart top; for
+    # shorter bars we place it just above the bar in dark text.
+    high_bar_threshold = 0.9
+    for bar, value in zip(bars, values):
+        x = bar.get_x() + bar.get_width() / 2
+        if value >= high_bar_threshold:
+            ax.text(
+                x,
+                value - 0.03,
+                f"{value:.1%}",
+                ha="center",
+                va="top",
+                fontsize=11,
+                fontweight="bold",
+                color="white",
+            )
+        else:
+            ax.text(
+                x,
+                value + 0.02,
+                f"{value:.1%}",
+                ha="center",
+                va="bottom",
+                fontsize=11,
+                fontweight="bold",
+                color="#222222",
+            )
+
+    ax.set_ylim(0.0, 1.0)
+    ax.set_ylabel("Posterior probability")
+    if title is not None:
+        ax.set_title(title)
+
+    return ax

abtestwise/result.py

@@ -0,0 +1,209 @@
+"""Result object for binary A/B tests."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import math
+
+import numpy as np
+
+from . import validation
+
+
+def _format_percent(x: float, digits: int = 2) -> str:
+    """Format a proportion as a percent string."""
+    if x is None or (isinstance(x, float) and math.isnan(x)):
+        return "undefined"
+    return f"{x * 100:.{digits}f}%"
+
+
+def _format_pp(x: float, digits: int = 2) -> str:
+    """Format a proportion difference as signed percentage points."""
+    if x is None or (isinstance(x, float) and math.isnan(x)):
+        return "undefined"
+    return f"{x * 100:+.{digits}f}"
+
+
+def _format_probability(x: float, digits: int = 1) -> str:
+    """Format a probability as a percent string."""
+    if x is None or (isinstance(x, float) and math.isnan(x)):
+        return "undefined"
+    return f"{x * 100:.{digits}f}%"
+
+
+@dataclass(frozen=True)
+class BinaryABResult:
+    """Results from a binary A/B test.
+
+    Lift is always Treatment B - Control A.
+    """
+
+    # Inputs
+    control_successes: int
+    control_total: int
+    treatment_successes: int
+    treatment_total: int
+    prior_alpha: float
+    prior_beta: float
+    n_simulations: int
+    credible_interval: float
+    seed: int | None
+
+    # Observed and frequentist results
+    control_rate: float
+    treatment_rate: float
+    absolute_lift: float
+    relative_lift: float
+    z_statistic: float
+    p_value: float
+
+    # Bayesian results
+    posterior_mean_lift: float
+    posterior_median_lift: float
+    prob_treatment_better: float
+    prob_control_better: float
+    credible_interval_bounds: tuple[float, float]
+    expected_loss_treatment: float
+    expected_loss_control: float
+
+    # Posterior samples
+    lift_samples: np.ndarray = field(repr=False)
+
+    def prob_lift_above(self, threshold: float) -> float:
+        """Return the posterior probability that lift is above a threshold."""
+        return float(np.mean(self.lift_samples > threshold))
+
+    def prob_no_harm(self, margin: float = 0.0) -> float:
+        """Posterior probability that Treatment B does no harm beyond ``margin``.
+
+        Computes ``P(lift >= -margin | data)``, where lift is
+        ``treatment_rate - control_rate``. ``margin`` is in raw decimal units, so
+        ``margin=0.005`` means "Treatment B is not worse than Control A by more
+        than 0.5 percentage points". With ``margin=0.0`` this is the probability
+        that lift is at least zero.
+        """
+        validation.validate_margin(margin)
+        return float(np.mean(self.lift_samples >= -margin))
+
+    def prob_harm_above(self, margin: float = 0.0) -> float:
+        """Posterior probability that Treatment B is harmful beyond ``margin``.
+
+        Computes ``P(lift < -margin | data)``, the exact complement of
+        :meth:`prob_no_harm` for the same ``margin``.
+        """
+        validation.validate_margin(margin)
+        return float(np.mean(self.lift_samples < -margin))
+
+    def plot_lift_distribution(
+        self,
+        ax: Any = None,
+        *,
+        bins: int = 50,
+        density: bool = True,
+        title: str | None = "Posterior Distribution of Lift",
+    ) -> Any:
+        """Plot the posterior lift distribution."""
+        from . import plotting
+
+        return plotting.plot_lift_distribution(
+            self.lift_samples,
+            self.posterior_median_lift,
+            self.credible_interval_bounds,
+            self.credible_interval,
+            ax=ax,
+            bins=bins,
+            density=density,
+            title=title,
+        )
+
+    def plot_probability_bar(
+        self,
+        ax: Any = None,
+        *,
+        title: str | None = "Posterior Probability of Being Better",
+    ) -> Any:
+        """Plot the probability that each group is better."""
+        from . import plotting
+
+        return plotting.plot_probability_bar(
+            self.prob_treatment_better,
+            self.prob_control_better,
+            ax=ax,
+            title=title,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return result fields as a dictionary."""
+        return {
+            "control_successes": self.control_successes,
+            "control_total": self.control_total,
+            "treatment_successes": self.treatment_successes,
+            "treatment_total": self.treatment_total,
+            "prior_alpha": self.prior_alpha,
+            "prior_beta": self.prior_beta,
+            "n_simulations": self.n_simulations,
+            "credible_interval": self.credible_interval,
+            "seed": self.seed,
+            "control_rate": self.control_rate,
+            "treatment_rate": self.treatment_rate,
+            "absolute_lift": self.absolute_lift,
+            "relative_lift": self.relative_lift,
+            "z_statistic": self.z_statistic,
+            "p_value": self.p_value,
+            "posterior_mean_lift": self.posterior_mean_lift,
+            "posterior_median_lift": self.posterior_median_lift,
+            "prob_treatment_better": self.prob_treatment_better,
+            "prob_control_better": self.prob_control_better,
+            "credible_interval_bounds": self.credible_interval_bounds,
+            "expected_loss_treatment": self.expected_loss_treatment,
+            "expected_loss_control": self.expected_loss_control,
+        }
+
+    def summary(self) -> str:
+        """Return a formatted summary."""
+        ci_pct = self.credible_interval * 100
+        lower, upper = self.credible_interval_bounds
+
+        # Relative lift is a ratio, not percentage points.
+        if math.isnan(self.relative_lift):
+            relative_lift_str = "undefined"
+        else:
+            relative_lift_str = f"{self.relative_lift * 100:+.2f}%"
+
+        lines = [
+            "Binary A/B test result",
+            "=" * 40,
+            "Observed (lift is always Treatment B - Control A)",
+            f"  Control (A):   {self.control_successes} / {self.control_total} "
+            f"= {_format_percent(self.control_rate)}",
+            f"  Treatment (B): {self.treatment_successes} / {self.treatment_total} "
+            f"= {_format_percent(self.treatment_rate)}",
+            f"  Observed lift (B - A): {_format_pp(self.absolute_lift)} "
+            "percentage points",
+            f"  Relative lift: {relative_lift_str}",
+            "",
+            "Frequentist (two-sided pooled z-test)",
+            f"  z statistic: {self.z_statistic:+.4f}",
+            f"  p-value: {self.p_value:.4f}",
+            "",
+            f"Bayesian (Beta({self.prior_alpha:g}, {self.prior_beta:g}) prior, "
+            f"{self.n_simulations:,} sims)",
+            f"  Posterior mean lift: {_format_pp(self.posterior_mean_lift)} "
+            "percentage points",
+            f"  Posterior median lift: {_format_pp(self.posterior_median_lift)} "
+            "percentage points",
+            f"  P(Treatment B > Control A): "
+            f"{_format_probability(self.prob_treatment_better)}",
+            f"  P(Control A > Treatment B): "
+            f"{_format_probability(self.prob_control_better)}",
+            f"  {ci_pct:g}% credible interval for lift: "
+            f"[{_format_pp(lower)}, {_format_pp(upper)}] percentage points",
+            "  Expected loss",
+            f"    Choosing treatment B: "
+            f"{self.expected_loss_treatment * 100:.2f} percentage points",
+            f"    Choosing control A:   "
+            f"{self.expected_loss_control * 100:.2f} percentage points",
+        ]
+        return "\n".join(lines)

abtestwise/validation.py

@@ -0,0 +1,80 @@
+"""Input validation helpers."""
+
+from __future__ import annotations
+
+import math
+
+
+def validate_count(name: str, value: int) -> None:
+    """Validate a non-negative integer count."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"{name} must be an integer, got {value!r}.")
+    if value < 0:
+        raise ValueError(f"{name} must be >= 0, got {value}.")
+
+
+def validate_total(name: str, value: int) -> None:
+    """Validate a positive integer total."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"{name} must be an integer, got {value!r}.")
+    if value <= 0:
+        raise ValueError(f"{name} must be > 0, got {value}.")
+
+
+def validate_successes_le_total(
+    successes_name: str,
+    successes: int,
+    total_name: str,
+    total: int,
+) -> None:
+    """Validate that successes do not exceed total."""
+    if successes > total:
+        raise ValueError(
+            f"{successes_name} ({successes}) cannot exceed {total_name} ({total})."
+        )
+
+
+def validate_prior(name: str, value: float) -> None:
+    """Validate a positive Beta prior parameter."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{name} must be a number, got {value!r}.")
+    if value <= 0:
+        raise ValueError(f"{name} must be > 0, got {value}.")
+
+
+def validate_credible_interval(value: float) -> None:
+    """Validate a credible interval level between 0 and 1."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"credible_interval must be a number, got {value!r}.")
+    if not (0.0 < value < 1.0):
+        raise ValueError(
+            f"credible_interval must be strictly between 0 and 1, got {value}."
+        )
+
+
+def validate_n_simulations(value: int) -> None:
+    """Validate a positive integer number of simulations."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"n_simulations must be an integer, got {value!r}.")
+    if value <= 0:
+        raise ValueError(f"n_simulations must be > 0, got {value}.")
+
+
+def validate_seed(value: int | None) -> None:
+    """Validate a random seed."""
+    if value is None:
+        return
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"seed must be None or an integer, got {value!r}.")
+    if value < 0:
+        raise ValueError(f"seed must be >= 0, got {value}.")
+
+
+def validate_margin(value: float) -> None:
+    """Validate a non-negative, finite do-no-harm margin."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"margin must be a number, got {value!r}.")
+    if not math.isfinite(value):
+        raise ValueError(f"margin must be finite, got {value}.")
+    if value < 0:
+        raise ValueError(f"margin must be >= 0, got {value}.")

abtestwise-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: abtestwise
+Version: 0.1.0
+Summary: Lightweight toolkit for binary A/B experiment analysis using aggregate counts.
+License: MIT
+Keywords: ab-testing,bayesian,experimentation,frequentist,statistics
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# abtestwise
+
+A lightweight Python toolkit for **binary A/B experiment analysis** using
+aggregate count data. Version 0.1 combines frequentist and Bayesian summaries
+for binary proportions.
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install abtestwise
+```
+
+## Development install
+
+To work on the package locally (with the test dependencies):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from abtestwise import BinaryABTest
+
+test = BinaryABTest.from_counts(
+    control_successes=120,
+    control_total=1000,
+    treatment_successes=145,
+    treatment_total=1000,
+    prior_alpha=1,
+    prior_beta=1,
+    n_simulations=100_000,
+    credible_interval=0.95,
+    seed=42,
+)
+
+result = test.run()
+
+print(result.summary())
+print(result.prob_lift_above(0.01))
+```
+
+`prob_lift_above(0.01)` gives the posterior probability that Treatment B improves
+the metric by more than 1 percentage point.
+
+### Do-no-harm checks
+
+`prob_no_harm(margin)` gives the posterior probability that Treatment B is **not**
+worse than Control A by more than `margin` (in raw decimal units, so `0.005` means
+0.5 percentage points). `prob_harm_above(margin)` is its complement.
+
+```python
+result.prob_no_harm(0.005)     # P(lift >= -0.005): B is not worse by more than 0.5pp
+result.prob_harm_above(0.005)  # P(lift <  -0.005): B is worse by more than 0.5pp
+```
+
+Raw result values are also available:
+
+```python
+result.to_dict()
+```
+
+## Plotting
+
+```python
+import matplotlib.pyplot as plt
+
+result.plot_lift_distribution()
+result.plot_probability_bar()
+
+plt.show()
+```
+
+The lift distribution plot shows posterior lift in percentage points.
+
+The probability bar plot shows:
+
+```text
+P(Treatment B > Control A)
+P(Control A > Treatment B)
+```
+
+## Groups and sign convention
+
+In product A/B testing terms:
+
+- **Control (A)** is the baseline group.
+- **Treatment (B)** is the test group or variant B.
+- **Lift is always Treatment B - Control A.**
+- **Positive lift means Treatment B is better than Control A.**
+- **Negative lift means Control A is better than Treatment B.**
+
+## Scope
+
+Current package scope:
+
+- Binary proportions only.
+- Aggregate counts only.
+- Two groups only.
+- Frequentist: two-sided pooled two-proportion z-test.
+- Bayesian: beta-binomial posterior simulation with default prior `Beta(1, 1)`.
+- Equal-tailed credible interval.
+- Expected loss.
+- Practical lift thresholds.
+- Do-no-harm probabilities using a user-defined harm margin.
+- Simple plots.
+
+## Development
+
+Run tests with:
+
+```bash
+python -m pytest -q
+```

abtestwise-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+abtestwise/__init__.py,sha256=S-NlVV4h2eFs3ClUNaEqYkMrjLr2m8IZ43j379THHXA,388
+abtestwise/bayesian.py,sha256=2Cz9Q9V170MOt275lM6Cy15JRsoG7q4CH87RXClfzUM,2350
+abtestwise/binary.py,sha256=2krX5pqcMP8yVMfnKPSY-FoPvFSPVx0DIV9D1DbcLcY,5132
+abtestwise/frequentist.py,sha256=gSkvwlA9-FZYyEcarRPCyLmdsfpkMsFTNK2-HhpmI7I,1377
+abtestwise/plotting.py,sha256=WVXFkT9oKCmnFPnBW8HtIglUgsNkWgZGEdxqroZVcO8,4243
+abtestwise/result.py,sha256=FHiPYjEBVI4vlBPrxpUBVMSOBALCCfVLoE7CwbBzCpo,7519
+abtestwise/validation.py,sha256=vu5n4TcXjPz2eKfuKVqM-J08MQ-z1nDZZcOj0CEKU4E,2883
+abtestwise-0.1.0.dist-info/METADATA,sha256=X4NoGjL2eKwTWNKwwIoxyvkHplk1Xukz7etUmpdPD5o,2952
+abtestwise-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+abtestwise-0.1.0.dist-info/RECORD,,

abtestwise-0.1.0.dist-info/WHEEL

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