experimentpy 0.1.0__tar.gz

experimentpy-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 — 2026-11-07
+
+- Binary-metric sample-size planning for independent two-arm A/B tests.
+- Equal and unequal allocation; absolute positive or negative MDE.
+- Pearson chi-square SRM checks for two or more arms.
+- Typed result dataclasses, input validation and executable examples.
+- Reference, edge-case and independent simulation tests.

experimentpy-0.1.0/LICENSE

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

experimentpy-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md CHANGELOG.md SUBIR_A_PYPI.md
+recursive-include tests *.py
+recursive-include examples *.py

experimentpy-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: experimentpy
+Version: 0.1.0
+Summary: Statistical tools for online experimentation: sample size and sample ratio mismatch.
+Author: Ubaldo Hervas
+License-Expression: MIT
+Keywords: ab-testing,experimentation,sample-size,srm,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# ExperimentPy
+
+Statistical tools for online experimentation.
+
+**Version 0.1.0** provides two working tools: sample-size planning for binary
+A/B metrics and sample ratio mismatch (SRM) checks. This library concerns
+statistical experiments; it is independent of the `pytest` software-testing framework.
+
+## Install
+
+Python 3.10 or newer is required. SciPy is the only direct runtime dependency.
+
+```bash
+pip install experimentpy
+```
+
+That command becomes available after publication on PyPI. To install the
+included wheel before publication, run this from the extracted project folder:
+
+```bash
+python -m pip install dist/experimentpy-0.1.0-py3-none-any.whl
+```
+
+## Sample size for a binary A/B metric
+
+```python
+from experimentpy import sample_size_proportions
+
+plan = sample_size_proportions(
+    baseline=0.05,        # 5% control conversion rate
+    mde_absolute=0.005,  # +0.5 percentage points: 5% -> 5.5%
+    alpha=0.05,
+    power=0.80,
+    ratio=1.0,           # variant units / control units
+)
+print(plan.n_control, plan.n_variant, plan.total)
+```
+
+An MDE of `0.005` means **0.5 percentage points**, or a **10% relative lift**
+on a 5% baseline. For a relative MDE, calculate `baseline * relative_lift`
+before calling the function. Negative absolute MDEs plan for decreases.
+
+The design uses a two-sided normal approximation for two independent
+proportions, pooled variance under the null and unpooled variance under the
+alternative. With `p0=baseline`, `p1=p0+mde_absolute`, and
+`r=n_variant/n_control`, the unrounded control sample size is:
+
+```text
+p_bar = (p0 + r*p1) / (1+r)
+n_control = (
+    (z_(1-alpha/2)*sqrt(p_bar*(1-p_bar)*(1+1/r))
+     + z_power*sqrt(p0*(1-p0) + p1*(1-p1)/r)) / abs(p1-p0)
+)**2
+```
+
+Arm sizes are rounded up. Power is approximate; there is no continuity
+correction. Designs with fewer than five expected events or non-events in
+either arm are rejected. This is a single-comparison, fixed-horizon design:
+repeated peeking, multiple comparisons and cluster randomization require
+different procedures. Users, sessions or other units must match the unit
+of independent randomization.
+
+## Sample ratio mismatch
+
+```python
+from experimentpy import check_srm
+
+quality = check_srm(
+    observed={"control": 5100, "variant": 4900},
+    allocation={"control": 0.5, "variant": 0.5},
+    alpha=0.001,
+)
+print(f"SRM p-value: {quality.pvalue:.4f}")
+print(f"SRM detected: {quality.has_srm}")
+```
+
+Pearson's goodness-of-fit test compares observed counts with the prespecified
+allocation, with `number_of_arms - 1` degrees of freedom. Omit `allocation`
+for equal allocation. Two or more arms are supported. Allocation proportions
+must be positive and sum to one, and expected counts must be at least five
+per arm. Counts must be nonnegative integers, not event totals or weights.
+
+Use each randomized unit once and avoid post-treatment filters. SRM signals
+an allocation discrepancy; it does not identify its cause. Absence of SRM
+does not establish overall experiment validity. The default SRM alpha is
+0.001 and is separate from the outcome-analysis alpha.
+
+Results are dataclasses and can be exported with `dataclasses.asdict(result)`.
+
+## Scope and next steps
+
+This release implements sample-size planning and SRM only. Outcome p-values,
+effect intervals, practical significance, variance reduction and
+quasi-experimental methods are planned extensions, not implemented APIs.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```
+
+Tests use Python's standard `unittest` framework; no `pytest` dependency is
+needed. See `examples/quickstart.py` for an executable example.
+
+## References
+
+- [SciPy Pearson chi-square documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.chisquare.html)
+- [statsmodels two-proportion power documentation](https://www.statsmodels.org/stable/generated/statsmodels.stats.proportion.power_proportions_2indep.html)
+
+## License
+
+MIT. Copyright (c) 2026 Ubaldo Hervas.

experimentpy-0.1.0/README.md

@@ -0,0 +1,115 @@
+# ExperimentPy
+
+Statistical tools for online experimentation.
+
+**Version 0.1.0** provides two working tools: sample-size planning for binary
+A/B metrics and sample ratio mismatch (SRM) checks. This library concerns
+statistical experiments; it is independent of the `pytest` software-testing framework.
+
+## Install
+
+Python 3.10 or newer is required. SciPy is the only direct runtime dependency.
+
+```bash
+pip install experimentpy
+```
+
+That command becomes available after publication on PyPI. To install the
+included wheel before publication, run this from the extracted project folder:
+
+```bash
+python -m pip install dist/experimentpy-0.1.0-py3-none-any.whl
+```
+
+## Sample size for a binary A/B metric
+
+```python
+from experimentpy import sample_size_proportions
+
+plan = sample_size_proportions(
+    baseline=0.05,        # 5% control conversion rate
+    mde_absolute=0.005,  # +0.5 percentage points: 5% -> 5.5%
+    alpha=0.05,
+    power=0.80,
+    ratio=1.0,           # variant units / control units
+)
+print(plan.n_control, plan.n_variant, plan.total)
+```
+
+An MDE of `0.005` means **0.5 percentage points**, or a **10% relative lift**
+on a 5% baseline. For a relative MDE, calculate `baseline * relative_lift`
+before calling the function. Negative absolute MDEs plan for decreases.
+
+The design uses a two-sided normal approximation for two independent
+proportions, pooled variance under the null and unpooled variance under the
+alternative. With `p0=baseline`, `p1=p0+mde_absolute`, and
+`r=n_variant/n_control`, the unrounded control sample size is:
+
+```text
+p_bar = (p0 + r*p1) / (1+r)
+n_control = (
+    (z_(1-alpha/2)*sqrt(p_bar*(1-p_bar)*(1+1/r))
+     + z_power*sqrt(p0*(1-p0) + p1*(1-p1)/r)) / abs(p1-p0)
+)**2
+```
+
+Arm sizes are rounded up. Power is approximate; there is no continuity
+correction. Designs with fewer than five expected events or non-events in
+either arm are rejected. This is a single-comparison, fixed-horizon design:
+repeated peeking, multiple comparisons and cluster randomization require
+different procedures. Users, sessions or other units must match the unit
+of independent randomization.
+
+## Sample ratio mismatch
+
+```python
+from experimentpy import check_srm
+
+quality = check_srm(
+    observed={"control": 5100, "variant": 4900},
+    allocation={"control": 0.5, "variant": 0.5},
+    alpha=0.001,
+)
+print(f"SRM p-value: {quality.pvalue:.4f}")
+print(f"SRM detected: {quality.has_srm}")
+```
+
+Pearson's goodness-of-fit test compares observed counts with the prespecified
+allocation, with `number_of_arms - 1` degrees of freedom. Omit `allocation`
+for equal allocation. Two or more arms are supported. Allocation proportions
+must be positive and sum to one, and expected counts must be at least five
+per arm. Counts must be nonnegative integers, not event totals or weights.
+
+Use each randomized unit once and avoid post-treatment filters. SRM signals
+an allocation discrepancy; it does not identify its cause. Absence of SRM
+does not establish overall experiment validity. The default SRM alpha is
+0.001 and is separate from the outcome-analysis alpha.
+
+Results are dataclasses and can be exported with `dataclasses.asdict(result)`.
+
+## Scope and next steps
+
+This release implements sample-size planning and SRM only. Outcome p-values,
+effect intervals, practical significance, variance reduction and
+quasi-experimental methods are planned extensions, not implemented APIs.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```
+
+Tests use Python's standard `unittest` framework; no `pytest` dependency is
+needed. See `examples/quickstart.py` for an executable example.
+
+## References
+
+- [SciPy Pearson chi-square documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.chisquare.html)
+- [statsmodels two-proportion power documentation](https://www.statsmodels.org/stable/generated/statsmodels.stats.proportion.power_proportions_2indep.html)
+
+## License
+
+MIT. Copyright (c) 2026 Ubaldo Hervas.

experimentpy-0.1.0/SUBIR_A_PYPI.md

@@ -0,0 +1,9 @@
+# Publicación de ExperimentPy 0.1.0
+
+Esta carpeta contiene el código y los archivos de distribución en `dist/`.
+El nombre queda registrado al aceptar PyPI la primera subida; disponer de
+los archivos localmente no lo reserva.
+
+La distribución se publica mediante Twine usando la cuenta del propietario.
+La autenticación de subida usa un token de PyPI. No añadas ese token al código,
+al repositorio ni a los archivos de distribución.

experimentpy-0.1.0/examples/quickstart.py

@@ -0,0 +1,9 @@
+"""Run after installing experimentpy: python examples/quickstart.py."""
+
+from experimentpy import check_srm, sample_size_proportions
+
+plan = sample_size_proportions(baseline=0.05, mde_absolute=0.005)
+print(f"Control: {plan.n_control:,}; variant: {plan.n_variant:,}; total: {plan.total:,}")
+
+quality = check_srm({"control": 5100, "variant": 4900})
+print(f"SRM p-value: {quality.pvalue:.4f}; detected: {quality.has_srm}")

experimentpy-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "experimentpy"
+version = "0.1.0"
+description = "Statistical tools for online experimentation: sample size and sample ratio mismatch."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Ubaldo Hervas"}]
+keywords = ["ab-testing", "experimentation", "sample-size", "srm", "statistics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["scipy>=1.10"]
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "twine>=5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+experimentpy = ["py.typed"]

experimentpy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

experimentpy-0.1.0/src/experimentpy/__init__.py

@@ -0,0 +1,9 @@
+"""Statistical tools for randomized online experiments."""
+
+from .design import SampleSizeResult, sample_size_proportions
+from .quality import SRMResult, check_srm
+
+__version__ = "0.1.0"
+__all__ = [
+    "SampleSizeResult", "SRMResult", "sample_size_proportions", "check_srm",
+]

experimentpy-0.1.0/src/experimentpy/_validation.py

@@ -0,0 +1,26 @@
+"""Shared input validation."""
+
+from math import isfinite
+from numbers import Integral, Real
+
+
+def finite_real(value: Real, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise ValueError(f"{name} must be a finite real number.")
+    result = float(value)
+    if not isfinite(result):
+        raise ValueError(f"{name} must be a finite real number.")
+    return result
+
+
+def probability(value: Real, name: str) -> float:
+    result = finite_real(value, name)
+    if not 0 < result < 1:
+        raise ValueError(f"{name} must be strictly between 0 and 1.")
+    return result
+
+
+def count(value: Integral, name: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, Integral) or value < 0:
+        raise ValueError(f"{name} must be a nonnegative integer count.")
+    return int(value)

experimentpy-0.1.0/src/experimentpy/design.py

@@ -0,0 +1,85 @@
+"""Fixed-horizon planning for two independent binary outcomes."""
+
+from dataclasses import dataclass
+from math import ceil, isfinite, sqrt
+
+from scipy.stats import norm
+
+from ._validation import finite_real, probability
+
+
+@dataclass(frozen=True)
+class SampleSizeResult:
+    """Required independent experimental units, rounded up by arm."""
+
+    n_control: int
+    n_variant: int
+    baseline: float
+    variant_rate: float
+    mde_absolute: float
+    alpha: float
+    power: float
+    ratio: float
+
+    @property
+    def total(self) -> int:
+        return self.n_control + self.n_variant
+
+
+def sample_size_proportions(
+    baseline: float,
+    mde_absolute: float,
+    *,
+    alpha: float = 0.05,
+    power: float = 0.80,
+    ratio: float = 1.0,
+) -> SampleSizeResult:
+    """Plan a two-sided, fixed-horizon, two-proportion z-test.
+
+    ``baseline`` and ``mde_absolute`` use proportions, not percentages:
+    baseline=0.05 and mde_absolute=0.005 plan for 5% versus 5.5%.
+    A negative MDE plans for a decrease. ``ratio`` is n_variant/n_control.
+
+    Uses a normal approximation with pooled null variance and unpooled
+    alternative variance, without continuity correction. Power is approximate.
+    Assumes independent Bernoulli units and a single planned comparison.
+    """
+    baseline = probability(baseline, "baseline")
+    alpha = probability(alpha, "alpha")
+    power = probability(power, "power")
+    if power <= max(0.5, alpha):
+        raise ValueError("power must exceed both 0.5 and alpha.")
+    mde_absolute = finite_real(mde_absolute, "mde_absolute")
+    if mde_absolute == 0:
+        raise ValueError("mde_absolute must be nonzero.")
+    variant = probability(baseline + mde_absolute, "baseline + mde_absolute")
+    ratio = finite_real(ratio, "ratio")
+    if ratio <= 0:
+        raise ValueError("ratio must be positive.")
+
+    # Weighted event rate across the two planned allocation sizes.
+    weight = ratio / (1.0 + ratio)
+    pooled = baseline * (1.0 - weight) + variant * weight
+    variance_null = pooled * (1.0 - pooled) * (1.0 + 1.0 / ratio)
+    variance_alternative = (
+        baseline * (1.0 - baseline) + variant * (1.0 - variant) / ratio
+    )
+    # isf avoids loss of precision from computing 1 - alpha/2.
+    critical = norm.isf(alpha / 2.0)
+    z_power = norm.ppf(power)
+    required = ((critical * sqrt(variance_null)
+                 + z_power * sqrt(variance_alternative)) / abs(mde_absolute)) ** 2
+    if not isfinite(required) or required <= 0:
+        raise ValueError("Inputs exceed the supported numerical range.")
+    n_control = max(1, ceil(required))
+    n_variant = max(1, ceil(ratio * n_control))
+    # Explicitly reject sparse designs instead of silently promising accuracy.
+    if min(n_control * baseline, n_control * (1 - baseline),
+           n_variant * variant, n_variant * (1 - variant)) < 5:
+        raise ValueError(
+            "The normal approximation requires at least 5 expected events "
+            "and non-events per arm; use an exact or simulation-based design."
+        )
+    return SampleSizeResult(
+        n_control, n_variant, baseline, variant, mde_absolute, alpha, power, ratio
+    )

experimentpy-0.1.0/src/experimentpy/quality.py

@@ -0,0 +1,74 @@
+"""Sample ratio mismatch checks on assignment counts."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from math import fsum, isclose
+
+from scipy.stats import chi2
+
+from ._validation import count, finite_real, probability
+
+
+@dataclass(frozen=True)
+class SRMResult:
+    """Pearson goodness-of-fit result for planned allocation proportions."""
+
+    labels: tuple[str, ...]
+    observed: tuple[int, ...]
+    expected: tuple[float, ...]
+    statistic: float
+    pvalue: float
+    degrees_of_freedom: int
+    alpha: float
+
+    @property
+    def has_srm(self) -> bool:
+        return self.pvalue < self.alpha
+
+
+def check_srm(
+    observed: Mapping[str, int],
+    allocation: Mapping[str, float] | None = None,
+    *,
+    alpha: float = 0.001,
+) -> SRMResult:
+    """Check assignment counts against a prespecified allocation.
+
+    Defaults to equal allocation. Allocation values must be positive
+    proportions summing to 1; keys must match observed exactly. Supports
+    two or more arms. Uses Pearson's chi-square with k-1 degrees of freedom.
+
+    Count each independent randomized unit once, before post-treatment
+    filters. A nonsignificant result does not establish experiment validity.
+    Raises ValueError if any expected arm count is below 5.
+    """
+    alpha = probability(alpha, "alpha")
+    if not isinstance(observed, Mapping) or len(observed) < 2:
+        raise ValueError("observed must map at least two arm labels to counts.")
+    labels = tuple(observed)
+    if any(not isinstance(label, str) or not label for label in labels):
+        raise ValueError("Arm labels must be nonempty strings.")
+    counts = tuple(count(observed[label], label) for label in labels)
+    total = sum(counts)
+    if total == 0:
+        raise ValueError("The total observed count must be positive.")
+    if allocation is None:
+        weights = (1.0 / len(labels),) * len(labels)
+    else:
+        if not isinstance(allocation, Mapping) or set(allocation) != set(labels):
+            raise ValueError("allocation and observed must have identical arm labels.")
+        weights = tuple(finite_real(allocation[label], label) for label in labels)
+        if any(weight <= 0 for weight in weights):
+            raise ValueError("Allocation proportions must be positive.")
+        if not isclose(fsum(weights), 1.0, rel_tol=0, abs_tol=1e-12):
+            raise ValueError("Allocation proportions must sum to 1.")
+        # Remove harmless floating-point summation error only.
+        weights = tuple(weight / fsum(weights) for weight in weights)
+    expected = tuple(total * weight for weight in weights)
+    if min(expected) < 5:
+        raise ValueError("Chi-square approximation requires expected counts >= 5 per arm.")
+    statistic = fsum((actual - target) ** 2 / target
+                     for actual, target in zip(counts, expected))
+    df = len(labels) - 1
+    pvalue = float(chi2.sf(statistic, df))
+    return SRMResult(labels, counts, expected, statistic, pvalue, df, alpha)

experimentpy-0.1.0/src/experimentpy.egg-info/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: experimentpy
+Version: 0.1.0
+Summary: Statistical tools for online experimentation: sample size and sample ratio mismatch.
+Author: Ubaldo Hervas
+License-Expression: MIT
+Keywords: ab-testing,experimentation,sample-size,srm,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# ExperimentPy
+
+Statistical tools for online experimentation.
+
+**Version 0.1.0** provides two working tools: sample-size planning for binary
+A/B metrics and sample ratio mismatch (SRM) checks. This library concerns
+statistical experiments; it is independent of the `pytest` software-testing framework.
+
+## Install
+
+Python 3.10 or newer is required. SciPy is the only direct runtime dependency.
+
+```bash
+pip install experimentpy
+```
+
+That command becomes available after publication on PyPI. To install the
+included wheel before publication, run this from the extracted project folder:
+
+```bash
+python -m pip install dist/experimentpy-0.1.0-py3-none-any.whl
+```
+
+## Sample size for a binary A/B metric
+
+```python
+from experimentpy import sample_size_proportions
+
+plan = sample_size_proportions(
+    baseline=0.05,        # 5% control conversion rate
+    mde_absolute=0.005,  # +0.5 percentage points: 5% -> 5.5%
+    alpha=0.05,
+    power=0.80,
+    ratio=1.0,           # variant units / control units
+)
+print(plan.n_control, plan.n_variant, plan.total)
+```
+
+An MDE of `0.005` means **0.5 percentage points**, or a **10% relative lift**
+on a 5% baseline. For a relative MDE, calculate `baseline * relative_lift`
+before calling the function. Negative absolute MDEs plan for decreases.
+
+The design uses a two-sided normal approximation for two independent
+proportions, pooled variance under the null and unpooled variance under the
+alternative. With `p0=baseline`, `p1=p0+mde_absolute`, and
+`r=n_variant/n_control`, the unrounded control sample size is:
+
+```text
+p_bar = (p0 + r*p1) / (1+r)
+n_control = (
+    (z_(1-alpha/2)*sqrt(p_bar*(1-p_bar)*(1+1/r))
+     + z_power*sqrt(p0*(1-p0) + p1*(1-p1)/r)) / abs(p1-p0)
+)**2
+```
+
+Arm sizes are rounded up. Power is approximate; there is no continuity
+correction. Designs with fewer than five expected events or non-events in
+either arm are rejected. This is a single-comparison, fixed-horizon design:
+repeated peeking, multiple comparisons and cluster randomization require
+different procedures. Users, sessions or other units must match the unit
+of independent randomization.
+
+## Sample ratio mismatch
+
+```python
+from experimentpy import check_srm
+
+quality = check_srm(
+    observed={"control": 5100, "variant": 4900},
+    allocation={"control": 0.5, "variant": 0.5},
+    alpha=0.001,
+)
+print(f"SRM p-value: {quality.pvalue:.4f}")
+print(f"SRM detected: {quality.has_srm}")
+```
+
+Pearson's goodness-of-fit test compares observed counts with the prespecified
+allocation, with `number_of_arms - 1` degrees of freedom. Omit `allocation`
+for equal allocation. Two or more arms are supported. Allocation proportions
+must be positive and sum to one, and expected counts must be at least five
+per arm. Counts must be nonnegative integers, not event totals or weights.
+
+Use each randomized unit once and avoid post-treatment filters. SRM signals
+an allocation discrepancy; it does not identify its cause. Absence of SRM
+does not establish overall experiment validity. The default SRM alpha is
+0.001 and is separate from the outcome-analysis alpha.
+
+Results are dataclasses and can be exported with `dataclasses.asdict(result)`.
+
+## Scope and next steps
+
+This release implements sample-size planning and SRM only. Outcome p-values,
+effect intervals, practical significance, variance reduction and
+quasi-experimental methods are planned extensions, not implemented APIs.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```
+
+Tests use Python's standard `unittest` framework; no `pytest` dependency is
+needed. See `examples/quickstart.py` for an executable example.
+
+## References
+
+- [SciPy Pearson chi-square documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.chisquare.html)
+- [statsmodels two-proportion power documentation](https://www.statsmodels.org/stable/generated/statsmodels.stats.proportion.power_proportions_2indep.html)
+
+## License
+
+MIT. Copyright (c) 2026 Ubaldo Hervas.

experimentpy-0.1.0/src/experimentpy.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+SUBIR_A_PYPI.md
+pyproject.toml
+examples/quickstart.py
+src/experimentpy/__init__.py
+src/experimentpy/_validation.py
+src/experimentpy/design.py
+src/experimentpy/py.typed
+src/experimentpy/quality.py
+src/experimentpy.egg-info/PKG-INFO
+src/experimentpy.egg-info/SOURCES.txt
+src/experimentpy.egg-info/dependency_links.txt
+src/experimentpy.egg-info/requires.txt
+src/experimentpy.egg-info/top_level.txt
+tests/test_statistics.py

experimentpy-0.1.0/src/experimentpy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

experimentpy-0.1.0/src/experimentpy.egg-info/requires.txt

@@ -0,0 +1,5 @@
+scipy>=1.10
+
+[dev]
+build>=1.2
+twine>=5

experimentpy-0.1.0/src/experimentpy.egg-info/top_level.txt

@@ -0,0 +1 @@
+experimentpy

experimentpy-0.1.0/tests/test_statistics.py

@@ -0,0 +1,126 @@
+"""Reference checks, invalid inputs, and independent Monte Carlo checks."""
+
+import math
+import unittest
+
+import numpy as np
+from scipy.stats import chisquare, norm
+
+from experimentpy import __version__, check_srm, sample_size_proportions
+
+
+class SampleSizeTests(unittest.TestCase):
+    def test_balanced_reference_design(self):
+        # Standard 5% -> 6% normal-approximation design: ~8150 per arm.
+        result = sample_size_proportions(0.05, 0.01)
+        self.assertTrue(8140 <= result.n_control <= 8160)
+        self.assertEqual(result.n_control, result.n_variant)
+        self.assertEqual(result.total, result.n_control * 2)
+
+    def test_mde_and_power_behaviour(self):
+        base = sample_size_proportions(0.05, 0.005)
+        self.assertGreater(base.total, sample_size_proportions(0.05, 0.01).total)
+        self.assertGreater(sample_size_proportions(0.05, 0.005, power=0.9).total, base.total)
+        self.assertGreater(sample_size_proportions(0.05, 0.005, alpha=0.01).total, base.total)
+
+    def test_unequal_allocation(self):
+        result = sample_size_proportions(0.10, 0.02, ratio=2)
+        self.assertEqual(result.n_variant, 2 * result.n_control)
+
+    def test_decrease_and_swapped_arms(self):
+        increase = sample_size_proportions(0.05, 0.01)
+        decrease = sample_size_proportions(0.06, -0.01)
+        self.assertEqual(increase.total, decrease.total)
+        self.assertLess(decrease.variant_rate, decrease.baseline)
+
+    def test_invalid_inputs(self):
+        cases = [
+            dict(baseline=0), dict(baseline=1), dict(baseline=True),
+            dict(baseline=float('nan')), dict(mde_absolute=0),
+            dict(mde_absolute=1), dict(mde_absolute=-0.1),
+            dict(mde_absolute='0.01'), dict(alpha=0), dict(alpha=float('inf')),
+            dict(power=1), dict(power=0.01), dict(power=0.5), dict(ratio=0), dict(ratio=-1),
+        ]
+        for case in cases:
+            args = dict(baseline=0.05, mde_absolute=0.005)
+            args.update(case)
+            with self.subTest(case=case), self.assertRaises(ValueError):
+                sample_size_proportions(**args)
+
+    def test_sparse_design_rejected(self):
+        with self.assertRaises(ValueError):
+            sample_size_proportions(0.000001, 0.1)
+
+    def test_power_with_independent_binomial_simulation(self):
+        # Independent generator and rejection rule check the complete design.
+        rng = np.random.default_rng(20261107)
+        for p0, delta, ratio in [(0.05, 0.01, 1), (0.1, 0.02, 2), (0.1, -0.02, 0.5)]:
+            with self.subTest(p0=p0, delta=delta, ratio=ratio):
+                plan = sample_size_proportions(p0, delta, ratio=ratio)
+                x0 = rng.binomial(plan.n_control, p0, size=30000)
+                x1 = rng.binomial(plan.n_variant, p0 + delta, size=30000)
+                pooled = (x0 + x1) / plan.total
+                se = np.sqrt(pooled * (1 - pooled) *
+                             (1 / plan.n_control + 1 / plan.n_variant))
+                z = (x1 / plan.n_variant - x0 / plan.n_control) / se
+                empirical = np.mean(np.abs(z) > norm.isf(0.025))
+                self.assertLess(abs(empirical - 0.80), 0.02)
+
+
+class SRMTests(unittest.TestCase):
+    def test_balanced_allocation(self):
+        result = check_srm({'control': 5000, 'variant': 5000})
+        self.assertEqual(result.statistic, 0)
+        self.assertEqual(result.pvalue, 1)
+        self.assertFalse(result.has_srm)
+
+    def test_hand_calculated_reference(self):
+        result = check_srm({'control': 600, 'variant': 400})
+        self.assertAlmostEqual(result.statistic, 40)
+        self.assertAlmostEqual(result.pvalue, math.erfc(math.sqrt(20)), places=20)
+        self.assertTrue(result.has_srm)
+
+    def test_unequal_allocation_and_mapping_order(self):
+        result = check_srm({'a': 200, 'b': 800}, {'b': 0.8, 'a': 0.2})
+        self.assertEqual(result.expected, (200., 800.))
+        self.assertEqual(result.pvalue, 1)
+
+    def test_multiple_arms_against_scipy(self):
+        result = check_srm({'a': 110, 'b': 190, 'c': 300},
+                           {'a': 1/6, 'b': 1/3, 'c': 1/2})
+        reference = chisquare([110, 190, 300], [100, 200, 300])
+        self.assertEqual(result.degrees_of_freedom, 2)
+        self.assertAlmostEqual(result.statistic, reference.statistic)
+        self.assertAlmostEqual(result.pvalue, reference.pvalue)
+
+    def test_zero_observed_arm_is_supported(self):
+        self.assertTrue(check_srm({'a': 0, 'b': 100}).has_srm)
+
+    def test_numpy_integer_counts(self):
+        self.assertEqual(check_srm({'a': np.int64(50), 'b': np.int64(50)}).pvalue, 1)
+
+    def test_invalid_counts(self):
+        cases = [{}, {'a': 10}, {'a': 0, 'b': 0}, {'a': 1, 'b': 1},
+                 {'a': -1, 'b': 100}, {'a': 1.5, 'b': 100},
+                 {'a': True, 'b': 100}, {'a': float('nan'), 'b': 100},
+                 {'': 100, 'b': 100}]
+        for case in cases:
+            with self.subTest(case=case), self.assertRaises(ValueError):
+                check_srm(case)
+
+    def test_invalid_allocations(self):
+        cases = [{'a': 50, 'b': 50}, {'a': 0, 'b': 1},
+                 {'a': -0.1, 'b': 1.1}, {'a': 0.5, 'c': 0.5},
+                 {'a': float('nan'), 'b': 0.5}]
+        for case in cases:
+            with self.subTest(case=case), self.assertRaises(ValueError):
+                check_srm({'a': 100, 'b': 100}, case)
+
+
+class PackageTests(unittest.TestCase):
+    def test_version(self):
+        self.assertEqual(__version__, '0.1.0')
+
+
+if __name__ == '__main__':
+    unittest.main()