ab-stats 0.1.0__tar.gz

ab_stats-0.1.0/LICENSE

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

ab_stats-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: ab-stats
+Version: 0.1.0
+Summary: A/B 테스트 통계적 검정에 필요한 결과를 제공하는 라이브러리
+Author: ab-stats contributors
+License: MIT
+Project-URL: Repository, https://github.com/noote-taking/ab-stats
+Project-URL: Documentation, https://github.com/noote-taking/ab-stats#readme
+Keywords: ab-test,statistics,hypothesis-testing,confidence-interval,p-value
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas>=1.3
+Requires-Dist: scipy>=1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# ab-stats
+
+**ab-stats** is a Python library that computes the statistics you need for A/B tests. It runs a **two-sample proportion z-test** for **rate (proportion) differences** and **Welch's t-test** for **mean differences** between control and treatment groups, and returns p-value, confidence intervals, uplift (relative change), and minimum sample size (MSS) in a pandas DataFrame.
+
+## Documentation
+
+- [README](https://github.com/noote-taking/ab-stats#readme)
+
+## Installation
+
+### Dependencies
+
+ab-stats depends on:
+
+- NumPy (>= 1.20)
+- Pandas (>= 1.3)
+- SciPy (>= 1.7)
+
+Python 3.8 or newer is required.
+
+### User installation
+
+Install from PyPI with pip:
+
+```bash
+pip install ab-stats
+```
+
+or with conda:
+
+```bash
+conda install -c conda-forge ab-stats
+```
+
+## Quick start
+
+### 1. Proportion (rate) difference — `proportions_ztest`
+
+Pass **sample sizes** and **success counts** for control and treatment; the function runs a two-sample proportion z-test and returns uplift, confidence intervals, and minimum sample size. **MSS** is the sample size required for the given α and β under the assumption that the observed effect is true; **it is computed post hoc and should be used as a reference only**.
+
+```python
+from ab_stats import proportions_ztest
+
+# Control: 101 successes out of 998; Treatment: 122 successes out of 1001
+df = proportions_ztest(
+    control_n=998,
+    control_success=101,
+    treatment_n=1001,
+    treatment_success=122,
+    alpha=0.05,
+    power=0.8,
+)
+print(df)
+```
+
+**Output:**
+
+| metric_formula | metric_value | delta_relative | delta_absolute | p_value | CI_relative | CI_absolute | MSS | statistic |
+|----------------|--------------|----------------|----------------|---------|-------------|-------------|-----|-----------|
+| 122/1001 | 0.1219 | 20.45 | 0.0207 | 0.14162 | [5.12%, 35.78%] | [-0.0069, 0.0483] | 152.3% (657) | 1.47 |
+
+### 2. Mean difference — `ttest_ind_welch`
+
+Pass **lists of values** for control and treatment; the function computes means, variances, and sample sizes internally and runs Welch's t-test.
+
+```python
+from ab_stats import ttest_ind_welch
+
+# Example: observation lists for control and treatment
+control = [10.1, 9.8, 11.2, 10.5, 9.9, 10.8, 10.3, 11.0, 9.7, 10.4, 9.8, 10.1]  # n=12
+treatment = [12.0, 11.5, 12.8, 11.9, 12.2, 12.5, 11.7, 12.1, 12.3, 11.8]  # n=10
+
+df = ttest_ind_welch(control, treatment, alpha=0.05, power=0.8)
+print(df)
+```
+
+**Output:**
+
+| metric_formula | metric_value | delta_relative | delta_absolute | p_value | CI_relative | CI_absolute | MSS | statistic | df |
+|----------------|--------------|----------------|----------------|---------|-------------|-------------|-----|-----------|-----|
+| 120/10 | 12.03 | 17.14 | 1.76 | 0.00273 | [8.21%, 26.07%] | [0.65, 2.87] | 45.2% (221) | 3.45 | 18.52 |
+
+### 3. Using with Pandas
+
+Results are returned as a pandas DataFrame, so you can merge with other columns or filter as usual.
+
+```python
+import pandas as pd
+from ab_stats import proportions_ztest, ttest_ind_welch
+
+# Proportion test
+result_prop = proportions_ztest(1000, 100, 1000, 120)
+# Use result_prop["p_value"], result_prop["CI_relative"], etc.
+
+# Mean test (lists → means, variances, n are computed inside the function)
+control_vals = [1.0, 2.0, 3.0, 4.0, 5.0]
+treatment_vals = [2.0, 3.0, 4.0, 5.0, 6.0]
+result_ttest = ttest_ind_welch(control_vals, treatment_vals)
+# Use result_ttest["metric_value"], result_ttest["df"], etc.
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

ab_stats-0.1.0/README.md

@@ -0,0 +1,104 @@
+# ab-stats
+
+**ab-stats** is a Python library that computes the statistics you need for A/B tests. It runs a **two-sample proportion z-test** for **rate (proportion) differences** and **Welch's t-test** for **mean differences** between control and treatment groups, and returns p-value, confidence intervals, uplift (relative change), and minimum sample size (MSS) in a pandas DataFrame.
+
+## Documentation
+
+- [README](https://github.com/noote-taking/ab-stats#readme)
+
+## Installation
+
+### Dependencies
+
+ab-stats depends on:
+
+- NumPy (>= 1.20)
+- Pandas (>= 1.3)
+- SciPy (>= 1.7)
+
+Python 3.8 or newer is required.
+
+### User installation
+
+Install from PyPI with pip:
+
+```bash
+pip install ab-stats
+```
+
+or with conda:
+
+```bash
+conda install -c conda-forge ab-stats
+```
+
+## Quick start
+
+### 1. Proportion (rate) difference — `proportions_ztest`
+
+Pass **sample sizes** and **success counts** for control and treatment; the function runs a two-sample proportion z-test and returns uplift, confidence intervals, and minimum sample size. **MSS** is the sample size required for the given α and β under the assumption that the observed effect is true; **it is computed post hoc and should be used as a reference only**.
+
+```python
+from ab_stats import proportions_ztest
+
+# Control: 101 successes out of 998; Treatment: 122 successes out of 1001
+df = proportions_ztest(
+    control_n=998,
+    control_success=101,
+    treatment_n=1001,
+    treatment_success=122,
+    alpha=0.05,
+    power=0.8,
+)
+print(df)
+```
+
+**Output:**
+
+| metric_formula | metric_value | delta_relative | delta_absolute | p_value | CI_relative | CI_absolute | MSS | statistic |
+|----------------|--------------|----------------|----------------|---------|-------------|-------------|-----|-----------|
+| 122/1001 | 0.1219 | 20.45 | 0.0207 | 0.14162 | [5.12%, 35.78%] | [-0.0069, 0.0483] | 152.3% (657) | 1.47 |
+
+### 2. Mean difference — `ttest_ind_welch`
+
+Pass **lists of values** for control and treatment; the function computes means, variances, and sample sizes internally and runs Welch's t-test.
+
+```python
+from ab_stats import ttest_ind_welch
+
+# Example: observation lists for control and treatment
+control = [10.1, 9.8, 11.2, 10.5, 9.9, 10.8, 10.3, 11.0, 9.7, 10.4, 9.8, 10.1]  # n=12
+treatment = [12.0, 11.5, 12.8, 11.9, 12.2, 12.5, 11.7, 12.1, 12.3, 11.8]  # n=10
+
+df = ttest_ind_welch(control, treatment, alpha=0.05, power=0.8)
+print(df)
+```
+
+**Output:**
+
+| metric_formula | metric_value | delta_relative | delta_absolute | p_value | CI_relative | CI_absolute | MSS | statistic | df |
+|----------------|--------------|----------------|----------------|---------|-------------|-------------|-----|-----------|-----|
+| 120/10 | 12.03 | 17.14 | 1.76 | 0.00273 | [8.21%, 26.07%] | [0.65, 2.87] | 45.2% (221) | 3.45 | 18.52 |
+
+### 3. Using with Pandas
+
+Results are returned as a pandas DataFrame, so you can merge with other columns or filter as usual.
+
+```python
+import pandas as pd
+from ab_stats import proportions_ztest, ttest_ind_welch
+
+# Proportion test
+result_prop = proportions_ztest(1000, 100, 1000, 120)
+# Use result_prop["p_value"], result_prop["CI_relative"], etc.
+
+# Mean test (lists → means, variances, n are computed inside the function)
+control_vals = [1.0, 2.0, 3.0, 4.0, 5.0]
+treatment_vals = [2.0, 3.0, 4.0, 5.0, 6.0]
+result_ttest = ttest_ind_welch(control_vals, treatment_vals)
+# Use result_ttest["metric_value"], result_ttest["df"], etc.
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

ab_stats-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ab-stats"
+version = "0.1.0"
+description = "A/B 테스트 통계적 검정에 필요한 결과를 제공하는 라이브러리"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [
+    { name = "ab-stats contributors" }
+]
+keywords = ["ab-test", "statistics", "hypothesis-testing", "confidence-interval", "p-value"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+
+dependencies = [
+    "numpy>=1.20",
+    "pandas>=1.3",
+    "scipy>=1.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.urls]
+Repository = "https://github.com/noote-taking/ab-stats"
+Documentation = "https://github.com/noote-taking/ab-stats#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

ab_stats-0.1.0/setup.cfg

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

ab_stats-0.1.0/src/ab_stats/stats.py

@@ -0,0 +1,277 @@
+"""
+A/B 테스트 통계 검정: 비율 차이(z-test), 평균 차이(Welch t-test)
+
+리스트/관측수를 받아 함수 내부에서 평균·분산·표본크기를 계산한 뒤 검정합니다
+"""
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+from scipy.stats import t, norm
+
+
+def _to_valid_arrays(control_values, treatment_values):
+    """
+    리스트를 numpy 배열로 변환하고, NaN을 제거
+    """
+    x = np.asarray(control_values, dtype=float)
+    y = np.asarray(treatment_values, dtype=float)
+    x = x[~np.isnan(x)]
+    y = y[~np.isnan(y)]
+    return x, y
+
+
+def proportions_ztest(
+    control_n,
+    control_success,
+    treatment_n,
+    treatment_success,
+    alpha=0.05,
+    power=0.8,
+):
+    """
+    두 독립 비율의 차이에 대한 z-검정 (대조군 vs 실험군).
+
+    대조군/실험군의 관측수와 성공수를 받아, 실험군 비율이 대조군과 다른지 검정하고
+    증감률·신뢰구간·최소 샘플 수 등을 반환합니다.
+
+    Parameters
+    ----------
+    control_n : int
+        대조군 관측수.
+    control_success : int
+        대조군 성공수.
+    treatment_n : int
+        실험군 관측수.
+    treatment_success : int
+        실험군 성공수.
+    alpha : float, optional
+        유의수준 (default: 0.05).
+    power : float, optional
+        검정력 1 - beta (default: 0.8).
+
+    Returns
+    -------
+    pandas.DataFrame
+        한 행에 metric_formula, metric_value, delta_relative, delta_absolute,
+        p_value, CI_relative, CI_absolute, MSS, statistic 컬럼.
+    """
+    epsilon = 1e-10
+
+    if control_n <= 0 or treatment_n <= 0:
+        raise ValueError("control_n and treatment_n must be positive.")
+    if not (0 <= control_success <= control_n and 0 <= treatment_success <= treatment_n):
+        raise ValueError("Success counts must be between 0 and respective n.")
+
+    p1 = control_success / control_n
+    p2 = treatment_success / treatment_n
+    diff = p2 - p1
+
+    # 표준오차 및 z-통계량·p-value 직접 계산
+    # delta_se: 비율 차이(p2-p1)의 표준오차 (standard error)
+    delta_se = np.sqrt(p1 * (1 - p1) / control_n + p2 * (1 - p2) / treatment_n)
+    if delta_se <= 0:
+        delta_se = epsilon
+    stat_z = diff / delta_se  # stat_z: z-통계량
+    p_value = 2 * (1 - norm.cdf(abs(stat_z)))  # 양측검정 p-value
+
+    # metric_formula: 실험군 성공수/실험군 관측수
+    metric_formula = f"{treatment_success}/{treatment_n}"
+    metric_value = p2
+    delta_absolute = diff
+    delta_relative = (diff / p1) * 100 if p1 > epsilon else np.nan
+
+    # 신뢰구간 (비율 차이: z 사용)
+    # z_crit: 신뢰구간 계산을 위한 z-분포의 임계값 (양측검정 상위 α/2 지점)
+    z_crit = norm.ppf(1 - alpha / 2)
+    delta_ci_lower = diff - z_crit * delta_se  # CI: confidence interval (신뢰구간)
+    delta_ci_upper = diff + z_crit * delta_se
+    CI_absolute = f"[{delta_ci_lower:.4f}, {delta_ci_upper:.4f}]"
+
+    # 증감률(%) 신뢰구간
+    if p1 > epsilon:
+        uplift_se = np.sqrt(
+            (1 / p1**2) * p2 * (1 - p2) / treatment_n
+            + (p2**2 / p1**4) * p1 * (1 - p1) / control_n
+        )
+        uplift = (diff / p1) * 100
+        uplift_ci_lower = uplift - z_crit * uplift_se
+        uplift_ci_upper = uplift + z_crit * uplift_se
+        CI_relative = f"[{uplift_ci_lower:.2f}%, {uplift_ci_upper:.2f}%]"
+    else:
+        CI_relative = "[nan%, nan%]"
+
+    # MSS: Minimum Sample Size (최소 샘플 수) 대비 현재 비율
+    beta = 1 - power  # beta: 제2종 오류 확률
+    z_alpha = norm.ppf(1 - alpha / 2)  # z_alpha: 유의수준 α에 대한 z 임계값
+    z_beta = norm.ppf(1 - beta)  # z_beta: 검정력(1-β)에 대한 z 값
+    k = control_n / treatment_n if treatment_n > 0 else 0  # k: 대조군/실험군 샘플 비율
+
+    if k <= 0 or not (0 < p1 < 1 and 0 < p2 < 1):
+        MSS = "0.0% (∞)"
+    else:
+        delta_abs = abs(p2 - p1)  # delta_abs: 비율 차이의 절댓값
+        if delta_abs <= 0:
+            MSS = "0.0% (∞)"
+        else:
+            # n2_min: 검정력을 만족하기 위한 실험군 최소 샘플 수
+            n2_min = ((z_alpha + z_beta) ** 2) * (
+                (p1 * (1 - p1)) / k + p2 * (1 - p2)
+            ) / (delta_abs**2)
+            if np.isnan(n2_min) or n2_min <= 0:
+                MSS = "0.0% (∞)"
+            else:
+                min_n2 = int(np.ceil(n2_min))  # min_n2: 최소 샘플 수 (정수로 올림)
+                ratio_pct = (treatment_n / min_n2) * 100  # ratio_pct: 현재 샘플 수 / 최소 샘플 수 (%)
+                MSS = f"{ratio_pct:.1f}% ({min_n2:,})"
+
+    return pd.DataFrame(
+        [
+            {
+                "metric_formula": metric_formula,
+                "metric_value": metric_value,
+                "delta_relative": delta_relative,
+                "delta_absolute": delta_absolute,
+                "p_value": round(p_value, 5),
+                "CI_relative": CI_relative,
+                "CI_absolute": CI_absolute,
+                "MSS": MSS,
+                "statistic": round(float(stat_z), 2),
+            }
+        ]
+    )
+
+
+def ttest_ind_welch(
+    control_values,
+    treatment_values,
+    alpha=0.05,
+    power=0.8,
+):
+    """
+    두 독립 표본의 평균 차이에 대한 Welch t-검정.
+
+    대조군/실험군 **값의 리스트**를 받아, 함수 내부에서 평균·분산·표본크기를 계산한 뒤
+    Welch-Satterthwaite 자유도로 검정합니다.
+
+    Parameters
+    ----------
+    control_values : array_like
+        대조군 관측값 리스트 (또는 배열).
+    treatment_values : array_like
+        실험군 관측값 리스트 (또는 배열).
+    alpha : float, optional
+        유의수준 (default: 0.05).
+    power : float, optional
+        검정력 1 - beta (default: 0.8).
+
+    Returns
+    -------
+    pandas.DataFrame
+        한 행에 metric_formula, metric_value, delta_relative, delta_absolute,
+        p_value, CI_relative, CI_absolute, MSS, statistic, df 컬럼.
+    """
+    x, y = _to_valid_arrays(control_values, treatment_values)
+    n1, n2 = len(x), len(y)
+
+    if n1 <= 1 or n2 <= 1:
+        raise ValueError(
+            "Each group must have at least 2 observations (for variance). "
+            f"Got control n={n1}, treatment n={n2}."
+        )
+
+    # 리스트 기준: 관측수 = len, 누적값 = sum (0 포함)
+    treatment_sum = float(np.sum(y))
+    mu1 = float(np.mean(x))
+    mu2 = float(np.mean(y))
+    # 표본 분산 (ddof=1)
+    s1_sq = float(np.var(x, ddof=1)) if n1 > 1 else 0.0
+    s2_sq = float(np.var(y, ddof=1)) if n2 > 1 else 0.0
+
+    # metric_formula: 실험군 누적값/실험군 관측수 (분자는 정수로 표기, 합계가 소수인 경우 없음)
+    metric_formula = f"{int(treatment_sum)}/{n2}"
+    metric_value = mu2
+
+    # Welch t-통계량 및 자유도
+    se = np.sqrt(s1_sq / n1 + s2_sq / n2)  # se: standard error (표준오차)
+    if se <= 0:
+        se = 1e-10
+    t_stat = (mu2 - mu1) / se  # t_stat: t-통계량
+
+    # Welch-Satterthwaite 자유도 계산: 분자(num_df)와 분모(den_df)
+    num_df = (s1_sq / n1 + s2_sq / n2) ** 2  # num_df: numerator of degrees of freedom
+    den_df = (s1_sq / n1) ** 2 / (n1 - 1) + (s2_sq / n2) ** 2 / (n2 - 1)  # den_df: denominator
+    df_welch = num_df / den_df if den_df > 0 else np.nan  # df_welch: Welch 자유도
+
+    # 두 그룹 모두 분산 0(상수)이면 자유도·p-value·CI 무의미 → NaN 반환
+    if np.isfinite(df_welch) and df_welch > 0:
+        p_value = 2 * (1 - stats.t.cdf(abs(t_stat), df=df_welch))
+        # t_crit_for_ci: 신뢰구간(CI) 계산을 위한 t-분포의 임계값 (critical value)
+        # 양측검정에서 상위 α/2 지점의 t 값 (예: α=0.05면 97.5% 지점)
+        t_crit_for_ci = t.ppf(1 - alpha / 2, df_welch)
+    else:
+        p_value = np.nan
+        t_crit_for_ci = np.nan
+
+    diff = mu2 - mu1
+    delta_absolute = diff
+    epsilon = 1e-10
+    delta_relative = (diff / mu1) * 100 if abs(mu1) > epsilon else np.nan
+
+    # 신뢰구간 (평균 차이: t 사용)
+    delta_ci_lower = diff - t_crit_for_ci * se
+    delta_ci_upper = diff + t_crit_for_ci * se
+    CI_absolute = f"[{delta_ci_lower:.4f}, {delta_ci_upper:.4f}]"
+
+    # 증감률(%) 신뢰구간
+    if abs(mu1) > epsilon:
+        # uplift_se: 증감률(uplift = (μ2-μ1)/μ1 * 100%)의 표준오차
+        uplift_se = np.sqrt(
+            (1 / max(mu1, epsilon) ** 2) * s2_sq / n2
+            + (mu2**2 / max(mu1, epsilon) ** 4) * s1_sq / n1
+        )
+        uplift = (diff / mu1) * 100  # uplift: 증감률 (%)
+        uplift_ci_lower = uplift - t_crit_for_ci * uplift_se
+        uplift_ci_upper = uplift + t_crit_for_ci * uplift_se
+        CI_relative = f"[{uplift_ci_lower:.2f}%, {uplift_ci_upper:.2f}%]"
+    else:
+        CI_relative = "[nan%, nan%]"
+
+    # MSS: Minimum Sample Size (최소 샘플 수) - 평균 차이 기준 (Welch 가정, k = n1/n2)
+    beta = 1 - power  # beta: 제2종 오류 확률
+    z_alpha = norm.ppf(1 - alpha / 2)  # z_alpha: 유의수준 α에 대한 z 임계값
+    z_beta = norm.ppf(1 - beta)  # z_beta: 검정력(1-β)에 대한 z 값
+    k = n1 / n2 if n2 > 0 else 0  # k: 대조군/실험군 샘플 비율
+
+    if k <= 0:
+        MSS = "0.0% (∞)"
+    else:
+        delta_abs = abs(mu2 - mu1)  # delta_abs: 평균 차이의 절댓값
+        if delta_abs <= 0 or np.isnan(delta_abs):
+            MSS = "0.0% (∞)"
+        else:
+            # n2_min: 검정력을 만족하기 위한 실험군 최소 샘플 수
+            n2_min = ((z_alpha + z_beta) ** 2) * (s1_sq / k + s2_sq) / (delta_abs**2)
+            if np.isnan(n2_min) or n2_min <= 0:
+                MSS = "0.0% (∞)"
+            else:
+                min_n2 = int(np.ceil(n2_min))  # min_n2: 최소 샘플 수 (정수로 올림)
+                ratio_pct = (n2 / min_n2) * 100  # ratio_pct: 현재 샘플 수 / 최소 샘플 수 (%)
+                MSS = f"{ratio_pct:.1f}% ({min_n2:,})"
+
+    return pd.DataFrame(
+        [
+            {
+                "metric_formula": metric_formula,
+                "metric_value": metric_value,
+                "delta_relative": delta_relative,
+                "delta_absolute": delta_absolute,
+                "p_value": round(p_value, 5),
+                "CI_relative": CI_relative,
+                "CI_absolute": CI_absolute,
+                "MSS": MSS,
+                "statistic": round(float(t_stat), 2),
+                "df": round(float(df_welch), 2),
+            }
+        ]
+    )

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

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: ab-stats
+Version: 0.1.0
+Summary: A/B 테스트 통계적 검정에 필요한 결과를 제공하는 라이브러리
+Author: ab-stats contributors
+License: MIT
+Project-URL: Repository, https://github.com/noote-taking/ab-stats
+Project-URL: Documentation, https://github.com/noote-taking/ab-stats#readme
+Keywords: ab-test,statistics,hypothesis-testing,confidence-interval,p-value
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas>=1.3
+Requires-Dist: scipy>=1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# ab-stats
+
+**ab-stats** is a Python library that computes the statistics you need for A/B tests. It runs a **two-sample proportion z-test** for **rate (proportion) differences** and **Welch's t-test** for **mean differences** between control and treatment groups, and returns p-value, confidence intervals, uplift (relative change), and minimum sample size (MSS) in a pandas DataFrame.
+
+## Documentation
+
+- [README](https://github.com/noote-taking/ab-stats#readme)
+
+## Installation
+
+### Dependencies
+
+ab-stats depends on:
+
+- NumPy (>= 1.20)
+- Pandas (>= 1.3)
+- SciPy (>= 1.7)
+
+Python 3.8 or newer is required.
+
+### User installation
+
+Install from PyPI with pip:
+
+```bash
+pip install ab-stats
+```
+
+or with conda:
+
+```bash
+conda install -c conda-forge ab-stats
+```
+
+## Quick start
+
+### 1. Proportion (rate) difference — `proportions_ztest`
+
+Pass **sample sizes** and **success counts** for control and treatment; the function runs a two-sample proportion z-test and returns uplift, confidence intervals, and minimum sample size. **MSS** is the sample size required for the given α and β under the assumption that the observed effect is true; **it is computed post hoc and should be used as a reference only**.
+
+```python
+from ab_stats import proportions_ztest
+
+# Control: 101 successes out of 998; Treatment: 122 successes out of 1001
+df = proportions_ztest(
+    control_n=998,
+    control_success=101,
+    treatment_n=1001,
+    treatment_success=122,
+    alpha=0.05,
+    power=0.8,
+)
+print(df)
+```
+
+**Output:**
+
+| metric_formula | metric_value | delta_relative | delta_absolute | p_value | CI_relative | CI_absolute | MSS | statistic |
+|----------------|--------------|----------------|----------------|---------|-------------|-------------|-----|-----------|
+| 122/1001 | 0.1219 | 20.45 | 0.0207 | 0.14162 | [5.12%, 35.78%] | [-0.0069, 0.0483] | 152.3% (657) | 1.47 |
+
+### 2. Mean difference — `ttest_ind_welch`
+
+Pass **lists of values** for control and treatment; the function computes means, variances, and sample sizes internally and runs Welch's t-test.
+
+```python
+from ab_stats import ttest_ind_welch
+
+# Example: observation lists for control and treatment
+control = [10.1, 9.8, 11.2, 10.5, 9.9, 10.8, 10.3, 11.0, 9.7, 10.4, 9.8, 10.1]  # n=12
+treatment = [12.0, 11.5, 12.8, 11.9, 12.2, 12.5, 11.7, 12.1, 12.3, 11.8]  # n=10
+
+df = ttest_ind_welch(control, treatment, alpha=0.05, power=0.8)
+print(df)
+```
+
+**Output:**
+
+| metric_formula | metric_value | delta_relative | delta_absolute | p_value | CI_relative | CI_absolute | MSS | statistic | df |
+|----------------|--------------|----------------|----------------|---------|-------------|-------------|-----|-----------|-----|
+| 120/10 | 12.03 | 17.14 | 1.76 | 0.00273 | [8.21%, 26.07%] | [0.65, 2.87] | 45.2% (221) | 3.45 | 18.52 |
+
+### 3. Using with Pandas
+
+Results are returned as a pandas DataFrame, so you can merge with other columns or filter as usual.
+
+```python
+import pandas as pd
+from ab_stats import proportions_ztest, ttest_ind_welch
+
+# Proportion test
+result_prop = proportions_ztest(1000, 100, 1000, 120)
+# Use result_prop["p_value"], result_prop["CI_relative"], etc.
+
+# Mean test (lists → means, variances, n are computed inside the function)
+control_vals = [1.0, 2.0, 3.0, 4.0, 5.0]
+treatment_vals = [2.0, 3.0, 4.0, 5.0, 6.0]
+result_ttest = ttest_ind_welch(control_vals, treatment_vals)
+# Use result_ttest["metric_value"], result_ttest["df"], etc.
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

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

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/ab_stats/stats.py
+src/ab_stats.egg-info/PKG-INFO
+src/ab_stats.egg-info/SOURCES.txt
+src/ab_stats.egg-info/dependency_links.txt
+src/ab_stats.egg-info/requires.txt
+src/ab_stats.egg-info/top_level.txt
+tests/test_stats.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,7 @@
+numpy>=1.20
+pandas>=1.3
+scipy>=1.7
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0

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

@@ -0,0 +1 @@
+ab_stats

ab_stats-0.1.0/tests/test_stats.py

@@ -0,0 +1,126 @@
+"""
+ab_stats.stats 함수 테스트: proportions_ztest, ttest_ind_welch
+"""
+
+import numpy as np
+import pytest
+from scipy import stats as scipy_stats
+
+from ab_stats.stats import proportions_ztest, ttest_ind_welch
+
+
+# ---------------------------------------------------------------------------
+# proportions_ztest
+# ---------------------------------------------------------------------------
+
+def test_proportions_ztest_basic():
+    """기본: DataFrame 1행, 필수 컬럼 존재, p_value·statistic 범위"""
+    df = proportions_ztest(
+        control_n=1000,
+        control_success=100,
+        treatment_n=1000,
+        treatment_success=120,
+        alpha=0.05,
+        power=0.8,
+    )
+    assert len(df) == 1
+    for col in ["metric_formula", "metric_value", "delta_relative", "delta_absolute",
+                "p_value", "CI_relative", "CI_absolute", "MSS", "statistic"]:
+        assert col in df.columns
+
+    assert 0 <= df["p_value"].iloc[0] <= 1
+    assert df["metric_formula"].iloc[0] == "120/1000"
+    assert abs(df["metric_value"].iloc[0] - 0.12) < 1e-10
+    assert abs(df["delta_absolute"].iloc[0] - 0.02) < 1e-10
+
+
+def test_proportions_ztest_same_proportion():
+    """비율이 같으면 p_value가 크고, delta_absolute=0"""
+    df = proportions_ztest(
+        control_n=500,
+        control_success=100,
+        treatment_n=500,
+        treatment_success=100,
+    )
+    assert abs(df["delta_absolute"].iloc[0]) < 1e-10
+    assert df["p_value"].iloc[0] >= 0.99  # 동일 비율이면 p ≈ 1
+
+
+def test_proportions_ztest_invalid_n():
+    """관측수 0 이하면 ValueError"""
+    with pytest.raises(ValueError, match="must be positive"):
+        proportions_ztest(0, 0, 100, 50)
+    with pytest.raises(ValueError, match="must be positive"):
+        proportions_ztest(100, 50, 0, 0)
+
+
+def test_proportions_ztest_invalid_success():
+    """성공수 범위 벗어나면 ValueError"""
+    with pytest.raises(ValueError, match="Success counts"):
+        proportions_ztest(100, 101, 100, 50)
+    with pytest.raises(ValueError, match="Success counts"):
+        proportions_ztest(100, -1, 100, 50)
+
+
+# ---------------------------------------------------------------------------
+# ttest_ind_welch
+# ---------------------------------------------------------------------------
+
+def test_ttest_ind_welch_basic():
+    """기본: DataFrame 1행, 필수 컬럼, Welch t와 scipy 결과와 일치 (100개 이상 샘플)"""
+    np.random.seed(42)
+    n = 150  # 100개 이상 샘플로 실제에 가깝게
+    control = np.random.normal(10, 2, n)
+    treatment = np.random.normal(12, 2, n)
+
+    df = ttest_ind_welch(control.tolist(), treatment.tolist(), alpha=0.05, power=0.8)
+
+    assert len(df) == 1
+    for col in ["metric_formula", "metric_value", "delta_relative", "delta_absolute",
+                "p_value", "CI_relative", "CI_absolute", "MSS", "statistic", "df"]:
+        assert col in df.columns
+
+    # scipy Welch t-test와 통계량·p-value 비교 (동일 데이터)
+    t_scipy, p_scipy = scipy_stats.ttest_ind(treatment, control, equal_var=False)
+    # statistic은 소수 둘째 자리로 반올림되어 출력되므로 허용 오차 0.01
+    assert abs(df["statistic"].iloc[0] - t_scipy) < 0.01
+    assert abs(df["p_value"].iloc[0] - p_scipy) < 1e-5
+
+    assert 0 <= df["p_value"].iloc[0] <= 1
+    assert df["metric_value"].iloc[0] == pytest.approx(np.mean(treatment), rel=1e-10)
+
+
+def test_ttest_ind_welch_metric_formula():
+    """metric_formula = 실험군 누적값/실험군 관측수"""
+    control = [1.0, 2.0, 3.0]
+    treatment = [0, 0, 0, 200, 500]  # sum=700, n=5
+    df = ttest_ind_welch(control, treatment)
+    assert df["metric_formula"].iloc[0] == "700/5"
+    assert df["metric_value"].iloc[0] == pytest.approx(700 / 5, rel=1e-10)
+
+
+def test_ttest_ind_welch_too_few_observations():
+    """그룹당 2미만이면 ValueError"""
+    with pytest.raises(ValueError, match="at least 2 observations"):
+        ttest_ind_welch([1.0], [1.0, 2.0])
+    with pytest.raises(ValueError, match="at least 2 observations"):
+        ttest_ind_welch([1.0, 2.0], [3.0])
+
+
+def test_ttest_ind_welch_constant_groups():
+    """두 그룹 모두 상수(분산 0)면 p_value가 NaN, CI_absolute에 nan 포함"""
+    control = [5.0, 5.0, 5.0]
+    treatment = [7.0, 7.0, 7.0]
+    df = ttest_ind_welch(control, treatment)
+    assert np.isnan(df["p_value"].iloc[0])
+    assert "nan" in df["CI_absolute"].iloc[0].lower()
+
+
+def test_ttest_ind_welch_nan_removal():
+    """NaN이 있으면 제거 후 계산 (listwise deletion)"""
+    control = [1.0, 2.0, 3.0, np.nan]
+    treatment = [2.0, 3.0, 4.0]
+    # control은 3개만 사용되어야 함
+    df = ttest_ind_welch(control, treatment)
+    assert len(df) == 1
+    assert np.isfinite(df["p_value"].iloc[0]) or df["p_value"].iloc[0] is not None