correlation-tost 0.1.0__tar.gz

correlation_tost-0.1.0/LICENSE

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

correlation_tost-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: correlation-tost
+Version: 0.1.0
+Summary: TOST equivalence testing for Pearson correlations.
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# correlation-tost
+
+A lightweight Python implementation of the two one-sided tests (TOST) procedure for equivalence testing of Pearson correlations.
+
+The test uses Fisher's z transformation and has been numerically validated against R's `TOSTER::corsum_test`.
+
+## Installation
+
+Install directly from GitHub with `pip`:
+
+```bash
+pip install git+https://github.com/ArijanaBohr/correlation-tost.git
+```
+
+**Requirements:** Python ≥ 3.9, NumPy, SciPy
+
+## Quick start
+
+
+```python
+from correlation_tost import pearson_tost
+
+result = pearson_tost(
+    observed=0.30,  # observed Pearson correlation
+    target=0.30,    # target Pearson correlation
+    n=10_000,       # sample size
+    margin=0.10,    # equivalence margin
+    alpha=0.05,     # significance level
+)
+
+print(result["equivalent"])  # True / False
+print(result["p_value"])     # overall TOST p-value
+```
+
+The equivalence bounds are defined in Pearson correlation units as
+`[target - margin, target + margin]`. Fisher's z transformation is applied
+internally when performing the test.
+
+## Output
+
+`pearson_tost` returns a dictionary with the following keys:
+
+| Key            | Description                                                   |
+|----------------|---------------------------------------------------------------|
+| `p_value`      | Overall TOST p-value                                          |
+| `p_lower`      | p-value for the lower-bound test                              |
+| `p_upper`      | p-value for the upper-bound test                              |
+| `z_stat_lower` | Test statistic for the lower-bound test                       |
+| `z_stat_upper` | Test statistic for the upper-bound test                       |
+| `ci_lower`     | Lower confidence interval bound                               |
+| `ci_upper`     | Upper confidence interval bound                               |
+| `equivalent`   | Whether equivalence is concluded at the specified `alpha`     |
+
+## Validation
+
+The implementation was independently validated against
+`TOSTER::corsum_test(method = "pearson", alternative = "equivalence")`
+across:
+
+- positive, negative, and zero correlations
+- multiple sample sizes
+- multiple equivalence margins
+- a range of correlation strengths
+
+The package itself does **not** depend on R, rpy2, or TOSTER.

correlation_tost-0.1.0/README.md

@@ -0,0 +1,65 @@
+# correlation-tost
+
+A lightweight Python implementation of the two one-sided tests (TOST) procedure for equivalence testing of Pearson correlations.
+
+The test uses Fisher's z transformation and has been numerically validated against R's `TOSTER::corsum_test`.
+
+## Installation
+
+Install directly from GitHub with `pip`:
+
+```bash
+pip install git+https://github.com/ArijanaBohr/correlation-tost.git
+```
+
+**Requirements:** Python ≥ 3.9, NumPy, SciPy
+
+## Quick start
+
+
+```python
+from correlation_tost import pearson_tost
+
+result = pearson_tost(
+    observed=0.30,  # observed Pearson correlation
+    target=0.30,    # target Pearson correlation
+    n=10_000,       # sample size
+    margin=0.10,    # equivalence margin
+    alpha=0.05,     # significance level
+)
+
+print(result["equivalent"])  # True / False
+print(result["p_value"])     # overall TOST p-value
+```
+
+The equivalence bounds are defined in Pearson correlation units as
+`[target - margin, target + margin]`. Fisher's z transformation is applied
+internally when performing the test.
+
+## Output
+
+`pearson_tost` returns a dictionary with the following keys:
+
+| Key            | Description                                                   |
+|----------------|---------------------------------------------------------------|
+| `p_value`      | Overall TOST p-value                                          |
+| `p_lower`      | p-value for the lower-bound test                              |
+| `p_upper`      | p-value for the upper-bound test                              |
+| `z_stat_lower` | Test statistic for the lower-bound test                       |
+| `z_stat_upper` | Test statistic for the upper-bound test                       |
+| `ci_lower`     | Lower confidence interval bound                               |
+| `ci_upper`     | Upper confidence interval bound                               |
+| `equivalent`   | Whether equivalence is concluded at the specified `alpha`     |
+
+## Validation
+
+The implementation was independently validated against
+`TOSTER::corsum_test(method = "pearson", alternative = "equivalence")`
+across:
+
+- positive, negative, and zero correlations
+- multiple sample sizes
+- multiple equivalence margins
+- a range of correlation strengths
+
+The package itself does **not** depend on R, rpy2, or TOSTER.

correlation_tost-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "correlation-tost"
+version = "0.1.0"
+license = "MIT"
+description = "TOST equivalence testing for Pearson correlations."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "numpy>=1.23",
+    "scipy>=1.9",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

correlation_tost-0.1.0/setup.cfg

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

correlation_tost-0.1.0/src/correlation_tost/__init__.py

@@ -0,0 +1,3 @@
+from ._tost import pearson_tost
+
+__all__ = ["pearson_tost"]

correlation_tost-0.1.0/src/correlation_tost/_tost.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import numpy as np
+from scipy.stats import norm
+
+
+def pearson_tost(
+    observed: float,
+    target: float,
+    n: int,
+    margin: float = 0.10,
+    alpha: float = 0.05,
+) -> dict[str, float | bool]:
+    """Test equivalence between an observed and target Pearson correlation.
+
+    Equivalence is assessed using two one-sided tests (TOST) after applying
+    Fisher's z transformation to the observed correlation and equivalence
+    bounds.
+
+    Parameters
+    ----------
+    observed
+        Observed Pearson correlation coefficient.
+    target
+        Target Pearson correlation coefficient.
+    n
+        Sample size used to estimate the observed correlation.
+    margin
+        Equivalence margin in Pearson correlation units. The equivalence
+        interval is ``[target - margin, target + margin]``.
+    alpha
+        Significance level for each one-sided test.
+
+    Returns
+    -------
+    dict
+        Test p-value, one-sided p-values, test statistics, confidence
+        interval, and equivalence decision.
+    """
+    if n <= 3:
+        raise ValueError("n must be greater than 3.")
+
+    if not -1 <= observed <= 1:
+        raise ValueError("observed must be between -1 and 1.")
+
+    if not -1 <= target <= 1:
+        raise ValueError("target must be between -1 and 1.")
+
+    if margin <= 0:
+        raise ValueError("margin must be greater than 0.")
+
+    if not 0 < alpha < 0.5:
+        raise ValueError("alpha must be between 0 and 0.5.")
+
+    eps = 1e-12
+
+    observed = float(np.clip(observed, -1 + eps, 1 - eps))
+    lower = float(np.clip(target - margin, -1 + eps, 1 - eps))
+    upper = float(np.clip(target + margin, -1 + eps, 1 - eps))
+
+    z_observed = np.arctanh(observed)
+    z_lower = np.arctanh(lower)
+    z_upper = np.arctanh(upper)
+
+    se = 1.0 / np.sqrt(n - 3)
+
+    # Lower one-sided test:
+    # H0: rho <= lower
+    # H1: rho > lower
+    z_stat_lower = (z_observed - z_lower) / se
+    p_lower = norm.sf(z_stat_lower)
+
+    # Upper one-sided test:
+    # H0: rho >= upper
+    # H1: rho < upper
+    z_stat_upper = (z_observed - z_upper) / se
+    p_upper = norm.cdf(z_stat_upper)
+
+    # Both one-sided tests must reject for equivalence.
+    p_value = max(p_lower, p_upper)
+
+    # 100 * (1 - 2 * alpha)% confidence interval.
+    z_crit = norm.ppf(1 - alpha)
+    ci_lower = np.tanh(z_observed - z_crit * se)
+    ci_upper = np.tanh(z_observed + z_crit * se)
+
+    return {
+        "p_value": float(p_value),
+        "p_lower": float(p_lower),
+        "p_upper": float(p_upper),
+        "z_stat_lower": float(z_stat_lower),
+        "z_stat_upper": float(z_stat_upper),
+        "ci_lower": float(ci_lower),
+        "ci_upper": float(ci_upper),
+        "equivalent": bool(p_value < alpha),
+    }

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

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: correlation-tost
+Version: 0.1.0
+Summary: TOST equivalence testing for Pearson correlations.
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# correlation-tost
+
+A lightweight Python implementation of the two one-sided tests (TOST) procedure for equivalence testing of Pearson correlations.
+
+The test uses Fisher's z transformation and has been numerically validated against R's `TOSTER::corsum_test`.
+
+## Installation
+
+Install directly from GitHub with `pip`:
+
+```bash
+pip install git+https://github.com/ArijanaBohr/correlation-tost.git
+```
+
+**Requirements:** Python ≥ 3.9, NumPy, SciPy
+
+## Quick start
+
+
+```python
+from correlation_tost import pearson_tost
+
+result = pearson_tost(
+    observed=0.30,  # observed Pearson correlation
+    target=0.30,    # target Pearson correlation
+    n=10_000,       # sample size
+    margin=0.10,    # equivalence margin
+    alpha=0.05,     # significance level
+)
+
+print(result["equivalent"])  # True / False
+print(result["p_value"])     # overall TOST p-value
+```
+
+The equivalence bounds are defined in Pearson correlation units as
+`[target - margin, target + margin]`. Fisher's z transformation is applied
+internally when performing the test.
+
+## Output
+
+`pearson_tost` returns a dictionary with the following keys:
+
+| Key            | Description                                                   |
+|----------------|---------------------------------------------------------------|
+| `p_value`      | Overall TOST p-value                                          |
+| `p_lower`      | p-value for the lower-bound test                              |
+| `p_upper`      | p-value for the upper-bound test                              |
+| `z_stat_lower` | Test statistic for the lower-bound test                       |
+| `z_stat_upper` | Test statistic for the upper-bound test                       |
+| `ci_lower`     | Lower confidence interval bound                               |
+| `ci_upper`     | Upper confidence interval bound                               |
+| `equivalent`   | Whether equivalence is concluded at the specified `alpha`     |
+
+## Validation
+
+The implementation was independently validated against
+`TOSTER::corsum_test(method = "pearson", alternative = "equivalence")`
+across:
+
+- positive, negative, and zero correlations
+- multiple sample sizes
+- multiple equivalence margins
+- a range of correlation strengths
+
+The package itself does **not** depend on R, rpy2, or TOSTER.

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

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/correlation_tost/__init__.py
+src/correlation_tost/_tost.py
+src/correlation_tost.egg-info/PKG-INFO
+src/correlation_tost.egg-info/SOURCES.txt
+src/correlation_tost.egg-info/dependency_links.txt
+src/correlation_tost.egg-info/requires.txt
+src/correlation_tost.egg-info/top_level.txt
+tests/test_tost.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,5 @@
+numpy>=1.23
+scipy>=1.9
+
+[test]
+pytest>=7

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

@@ -0,0 +1 @@
+correlation_tost

correlation_tost-0.1.0/tests/test_tost.py

@@ -0,0 +1,51 @@
+import pytest
+
+from correlation_tost import pearson_tost
+
+
+def test_matches_toster_reference_case():
+    """Match a reference result from TOSTER::corsum_test."""
+    result = pearson_tost(
+        observed=0.30,
+        target=0.30,
+        n=10_000,
+        margin=0.10,
+        alpha=0.05,
+    )
+
+    assert result["p_value"] == pytest.approx(
+        6.513681924396496e-27,
+        rel=1e-12,
+    )
+    assert result["ci_lower"] == pytest.approx(
+        0.2849567,
+        abs=1e-7,
+    )
+    assert result["ci_upper"] == pytest.approx(
+        0.3148956,
+        abs=1e-7,
+    )
+    assert result["equivalent"] is True
+
+
+@pytest.mark.parametrize(
+    "kwargs, message",
+    [
+        ({"n": 3}, "n must be greater than 3"),
+        ({"observed": 1.1}, "observed must be between -1 and 1"),
+        ({"target": -1.1}, "target must be between -1 and 1"),
+        ({"margin": 0.0}, "margin must be greater than 0"),
+        ({"alpha": 0.0}, "alpha must be between 0 and 0.5"),
+        ({"alpha": 0.5}, "alpha must be between 0 and 0.5"),
+    ],
+)
+def test_invalid_inputs(kwargs, message):
+    params = {
+        "observed": 0.30,
+        "target": 0.30,
+        "n": 100,
+    }
+    params.update(kwargs)
+
+    with pytest.raises(ValueError, match=message):
+        pearson_tost(**params)