critical-es-value 0.1.0__tar.gz

critical_es_value-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,32 @@
+name: Upload Python Package to PyPI
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  pypi-publish:
+    name: Publish release to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

critical_es_value-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Jupyter
+.ipynb_checkpoints
+
+*.ipynb
+data*.csv

critical_es_value-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

critical_es_value-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Florian Rohrer
+
+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.

critical_es_value-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: critical-es-value
+Version: 0.1.0
+Summary: Calculate critical effect size values.
+Author-email: Florian Rohrer <semicolonator@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: mpmath>=1.3.0
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pingouin>=0.5.5
+Description-Content-Type: text/markdown
+
+# critical_es_value
+
+Calculate critical effect size values for t-Tests, correlation tests and linear regression coefficients.
+
+## Usage
+
+```python
+import numpy as np
+import pingouin as pg
+
+from critical_es_value import (
+    critical_for_one_sample_ttest,
+    critical_for_two_sample_ttest,
+    critical_for_correlation_test,
+    critical_for_linear_regression,
+)
+
+np.random.seed(123)
+mean, cov, n = [4, 5], [(1, .6), (.6, 1)], 30
+x, y = np.random.multivariate_normal(mean, cov, n).T
+```
+
+### t-Test
+
+
+```python
+pg.ttest(x, 0)
+critical_for_one_sample_ttest(x)
+```
+
+|        |       T |   dof | alternative   |       p-val | CI95%       |   cohen-d |      BF10 |   power |
+|:-------|--------:|------:|:--------------|------------:|:------------|----------:|----------:|--------:|
+| T-test | 16.0765 |    29 | two-sided     | 5.54732e-16 | [3.37 4.35] |   2.93515 | 1.031e+13 |     nan |
+
+|          |       T |   dof |   T_critical |       d |   d_critical |   b_critical |       g |   g_critical |
+|:---------|--------:|------:|-------------:|--------:|-------------:|-------------:|--------:|-------------:|
+| critical | 16.0765 |    29 |      2.04523 | 2.93515 |     0.373406 |     0.491162 | 2.85847 |     0.363651 |
+
+```python
+pg.ttest(x, y)
+critical_for_two_sample_ttest(x, y)
+```
+
+|        |        T |   dof | alternative   |     p-val | CI95%         |   cohen-d |   BF10 |    power |
+|:-------|---------:|------:|:--------------|----------:|:--------------|----------:|-------:|---------:|
+| T-test | -3.40071 |    58 | two-sided     | 0.0012224 | [-1.68 -0.43] |  0.878059 | 26.155 | 0.916807 |
+
+
+|          |        T |   dof |   T_critical |         d |   d_critical |   b_critical |         g |   g_critical |
+|:---------|---------:|------:|-------------:|----------:|-------------:|-------------:|----------:|-------------:|
+| critical | -3.40071 |    58 |      2.00172 | -0.878059 |     0.516841 |      0.62077 | -0.866647 |     0.510124 |
+
+
+### Correlation Test
+
+```python
+pg.corr(x, y)
+critical_for_correlation_test(x, y)
+```
+
+|         |   n |        r | CI95%       |      p-val |   BF10 |    power |
+|:--------|----:|---------:|:------------|-----------:|-------:|---------:|
+| pearson |  30 | 0.594785 | [0.3  0.79] | 0.00052736 | 69.723 | 0.950373 |
+
+|          |   n |        r |   dof |   r_critical |    se_r |   se_r_critical |
+|:---------|----:|---------:|------:|-------------:|--------:|----------------:|
+| critical |  30 | 0.594785 |    28 |     0.361007 | 0.15192 |        0.176238 |
+
+
+### Linear Regression
+
+```python
+import pandas as pd
+
+np.random.seed(123)
+data = pd.DataFrame({"X": x, "Y": y, "Z": np.random.normal(5, 1, 30)})
+
+pg.linear_regression(data[["X", "Z"]], data["Y"])
+critical_for_linear_regression(data[["X", "Z"]], data["Y"])
+```
+
+|    | names     |       coef |       se |         T |        pval |       r2 |   adj_r2 |   CI[2.5%] |   CI[97.5%] |
+|---:|:----------|-----------:|---------:|----------:|------------:|---------:|---------:|-----------:|------------:|
+|  0 | Intercept |  3.15799   | 0.844129 |  3.74112  | 0.000874245 | 0.354522 | 0.306709 |   1.42598  |    4.88999  |
+|  1 | X         |  0.487772  | 0.126736 |  3.84871  | 0.000659501 | 0.354522 | 0.306709 |   0.22773  |    0.747814 |
+|  2 | Z         | -0.0249309 | 0.140417 | -0.177548 | 0.860403    | 0.354522 | 0.306709 |  -0.313044 |    0.263182 |
+
+|    | names     |       coef |   coef_critical |
+|---:|:----------|-----------:|----------------:|
+|  0 | Intercept |  3.15799   |        1.73201  |
+|  1 | X         |  0.487772  |        0.260042 |
+|  2 | Z         | -0.0249309 |        0.288113 |
+
+
+## Resources
+
+* [R package](https://psicostat.github.io/criticalESvalue/index.html)
+* [Original paper](https://journals.sagepub.com/doi/10.1177/25152459251335298?icid=int.sj-full-text.similar-articles.5)
+> Perugini, A., Gambarota, F., Toffalini, E., Lakens, D., Pastore, M., Finos, L., ... & Altoè, G. (2025). The Benefits of Reporting Critical-Effect-Size Values. Advances in Methods and Practices in Psychological Science, 8(2), 25152459251335298.
+

critical_es_value-0.1.0/README.md

@@ -0,0 +1,100 @@
+# critical_es_value
+
+Calculate critical effect size values for t-Tests, correlation tests and linear regression coefficients.
+
+## Usage
+
+```python
+import numpy as np
+import pingouin as pg
+
+from critical_es_value import (
+    critical_for_one_sample_ttest,
+    critical_for_two_sample_ttest,
+    critical_for_correlation_test,
+    critical_for_linear_regression,
+)
+
+np.random.seed(123)
+mean, cov, n = [4, 5], [(1, .6), (.6, 1)], 30
+x, y = np.random.multivariate_normal(mean, cov, n).T
+```
+
+### t-Test
+
+
+```python
+pg.ttest(x, 0)
+critical_for_one_sample_ttest(x)
+```
+
+|        |       T |   dof | alternative   |       p-val | CI95%       |   cohen-d |      BF10 |   power |
+|:-------|--------:|------:|:--------------|------------:|:------------|----------:|----------:|--------:|
+| T-test | 16.0765 |    29 | two-sided     | 5.54732e-16 | [3.37 4.35] |   2.93515 | 1.031e+13 |     nan |
+
+|          |       T |   dof |   T_critical |       d |   d_critical |   b_critical |       g |   g_critical |
+|:---------|--------:|------:|-------------:|--------:|-------------:|-------------:|--------:|-------------:|
+| critical | 16.0765 |    29 |      2.04523 | 2.93515 |     0.373406 |     0.491162 | 2.85847 |     0.363651 |
+
+```python
+pg.ttest(x, y)
+critical_for_two_sample_ttest(x, y)
+```
+
+|        |        T |   dof | alternative   |     p-val | CI95%         |   cohen-d |   BF10 |    power |
+|:-------|---------:|------:|:--------------|----------:|:--------------|----------:|-------:|---------:|
+| T-test | -3.40071 |    58 | two-sided     | 0.0012224 | [-1.68 -0.43] |  0.878059 | 26.155 | 0.916807 |
+
+
+|          |        T |   dof |   T_critical |         d |   d_critical |   b_critical |         g |   g_critical |
+|:---------|---------:|------:|-------------:|----------:|-------------:|-------------:|----------:|-------------:|
+| critical | -3.40071 |    58 |      2.00172 | -0.878059 |     0.516841 |      0.62077 | -0.866647 |     0.510124 |
+
+
+### Correlation Test
+
+```python
+pg.corr(x, y)
+critical_for_correlation_test(x, y)
+```
+
+|         |   n |        r | CI95%       |      p-val |   BF10 |    power |
+|:--------|----:|---------:|:------------|-----------:|-------:|---------:|
+| pearson |  30 | 0.594785 | [0.3  0.79] | 0.00052736 | 69.723 | 0.950373 |
+
+|          |   n |        r |   dof |   r_critical |    se_r |   se_r_critical |
+|:---------|----:|---------:|------:|-------------:|--------:|----------------:|
+| critical |  30 | 0.594785 |    28 |     0.361007 | 0.15192 |        0.176238 |
+
+
+### Linear Regression
+
+```python
+import pandas as pd
+
+np.random.seed(123)
+data = pd.DataFrame({"X": x, "Y": y, "Z": np.random.normal(5, 1, 30)})
+
+pg.linear_regression(data[["X", "Z"]], data["Y"])
+critical_for_linear_regression(data[["X", "Z"]], data["Y"])
+```
+
+|    | names     |       coef |       se |         T |        pval |       r2 |   adj_r2 |   CI[2.5%] |   CI[97.5%] |
+|---:|:----------|-----------:|---------:|----------:|------------:|---------:|---------:|-----------:|------------:|
+|  0 | Intercept |  3.15799   | 0.844129 |  3.74112  | 0.000874245 | 0.354522 | 0.306709 |   1.42598  |    4.88999  |
+|  1 | X         |  0.487772  | 0.126736 |  3.84871  | 0.000659501 | 0.354522 | 0.306709 |   0.22773  |    0.747814 |
+|  2 | Z         | -0.0249309 | 0.140417 | -0.177548 | 0.860403    | 0.354522 | 0.306709 |  -0.313044 |    0.263182 |
+
+|    | names     |       coef |   coef_critical |
+|---:|:----------|-----------:|----------------:|
+|  0 | Intercept |  3.15799   |        1.73201  |
+|  1 | X         |  0.487772  |        0.260042 |
+|  2 | Z         | -0.0249309 |        0.288113 |
+
+
+## Resources
+
+* [R package](https://psicostat.github.io/criticalESvalue/index.html)
+* [Original paper](https://journals.sagepub.com/doi/10.1177/25152459251335298?icid=int.sj-full-text.similar-articles.5)
+> Perugini, A., Gambarota, F., Toffalini, E., Lakens, D., Pastore, M., Finos, L., ... & Altoè, G. (2025). The Benefits of Reporting Critical-Effect-Size Values. Advances in Methods and Practices in Psychological Science, 8(2), 25152459251335298.
+

critical_es_value-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "critical-es-value"
+version = "0.1.0"
+description = "Calculate critical effect size values."
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "mpmath>=1.3.0",
+    "pandas>=2.3.3",
+    "pingouin>=0.5.5",
+]
+authors = [
+  {name = "Florian Rohrer", email = "semicolonator@gmail.com"},
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    "jupyter>=1.1.1",
+    "pytest>=8.4.2",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/critical_es_value"]

critical_es_value-0.1.0/src/critical_es_value/__init__.py

@@ -0,0 +1,13 @@
+from .corrtest import critical_for_correlation_test
+from .linreg import (
+    critical_for_linear_regression,
+    critical_for_linear_regression_se_coefficients,
+)
+from .ttest import (
+    critical_for_one_sample_ttest,
+    critical_for_two_sample_ttest,
+)
+from .utils import (
+    get_alpha,
+    get_bias_correction_factor_J,
+)

critical_es_value-0.1.0/src/critical_es_value/corrtest.py

@@ -0,0 +1,72 @@
+import numpy as np
+import pandas as pd
+import pingouin
+from numpy.typing import ArrayLike
+from scipy import stats
+
+from critical_es_value import utils
+
+
+def critical_for_correlation_test(
+    x: ArrayLike,
+    y: ArrayLike,
+    confidence: float = 0.95,
+    alternative: str = "two-sided",
+    variant: str = "ttest",
+) -> pd.DataFrame:
+    """Calculate critical effect size values for a pearson correlation test.
+
+    Returns a DataFrame with the following columns:
+     - r: Pearson correlation coefficient
+     - n: Sample size
+     - dof: Degrees of freedom
+     - r_critical: Critical value for the correlation coefficient
+     - rz_critical: Critical value for Fisher's z-transformed correlation coefficient (only for "ztest" variant)
+     - se_r: Standard error of the correlation coefficient
+     - se_r_critical: Standard error of the critical correlation coefficient
+     - se_rz_critical: Standard error of the critical Fisher's z-transformed correlation coefficient (only for "ztest" variant)
+
+    Args:
+        x (ArrayLike): Sample data for group 1.
+        y (ArrayLike): Sample data for group 2.
+        confidence (float): Confidence level between 0 and 1 (exclusive). Default is 0.95.
+        alternative (str): The alternative hypothesis. Either "two-sided", "greater", or "less". Default is "two-sided".
+        variant (str): The statistical test variant. Either "ttest" or "ztest". Default is "ttest".
+
+    Returns:
+        pd.DataFrame: A DataFrame containing critical effect size values.
+    """
+
+    if variant not in ["ttest", "ztest"]:
+        raise ValueError("variant must be one of 'ttest' or 'ztest'")
+
+    corr_test_result = pingouin.corr(
+        x, y, alternative=alternative, method="pearson"
+    ).iloc[0]
+
+    r = corr_test_result["r"]
+    n = corr_test_result["n"]
+
+    alpha = utils.get_alpha(confidence, alternative)
+    dof = n - 2
+
+    if variant == "ttest":
+        tc = np.abs(stats.t.ppf(alpha, dof))
+        rc = np.sqrt(tc**2 / (tc**2 + dof))
+    else:
+        zc = np.abs(stats.norm.ppf(alpha))
+        rc = np.tanh(zc / np.sqrt(n - 3))
+
+    result = {
+        "n": n,
+        "r": r,
+        "dof": dof,
+        "r_critical": rc,
+        "se_r": np.sqrt((1 - r**2) / dof),
+        "se_r_critical": np.sqrt((1 - rc**2) / dof),
+    }
+    if variant == "ztest":
+        result["rz_critical"] = np.atanh(rc)
+        result["se_rz_critical"] = 1 / np.sqrt(n - 3)
+
+    return pd.DataFrame([result], index=["critical"])

critical_es_value-0.1.0/src/critical_es_value/linreg.py

@@ -0,0 +1,97 @@
+import numpy as np
+import pandas as pd
+import pingouin
+from numpy.typing import ArrayLike
+from scipy import stats
+
+from critical_es_value import utils
+
+
+def critical_for_linear_regression_se_coefficients(
+    se_coefficients: ArrayLike,
+    dof: int,
+    confidence: float,
+    alternative: str,
+    variant: str = "ttest",
+) -> list[float]:
+    """Calculate critical effect size values for linear regression coefficients.
+
+    Args:
+        se_coefficients (ArrayLike): Standard errors of the regression coefficients.
+        dof (int): Degrees of freedom of the model residuals.
+        confidence (float): Confidence level between 0 and 1 (exclusive).
+        alternative (str): The alternative hypothesis. Either "two-sided", "greater", or "less".
+        variant (str): The statistical test variant. Either "ttest" or "ztest". Default is "ttest".
+
+    Returns:
+        np.ndarray: An array containing critical effect size values for each coefficient.
+
+    Raises:
+        ValueError: If variant is not one of "ttest" or "ztest".
+    """
+    if variant not in ["ttest", "ztest"]:
+        raise ValueError("variant must be one of 'ttest' or 'ztest'")
+
+    alpha = utils.get_alpha(confidence, alternative)
+
+    if variant == "ttest":
+        qc = np.abs(stats.t.ppf(alpha, dof))
+    else:
+        qc = np.abs(stats.norm.ppf(alpha))
+
+    return qc * np.array(se_coefficients)
+
+
+def critical_for_linear_regression(
+    X: pd.DataFrame,
+    y: pd.Series,
+    alternative: str = "two-sided",
+    confidence: float = 0.95,
+    variant: str = "ttest",
+    **kwargs,
+):
+    """Calculate critical effect size values for linear regression coefficients.
+
+    Returns a DataFrame with the following columns:
+     - names: Names of the regression coefficients
+     - coef: Estimated regression coefficients
+     - coef_critical: Critical value for the regression coefficients
+
+    Args:
+        X (pd.DataFrame): DataFrame containing the independent variables.
+        y (pd.Series): Series containing the dependent variable.
+        alternative (str): The alternative hypothesis. Either "two-sided", "greater", or "less". Default is "two-sided".
+        confidence (float): Confidence level between 0 and 1 (exclusive). Default is 0.95.
+        variant (str): The statistical test variant. Either "ttest" or "ztest". Default is "ttest".
+        **kwargs: Additional keyword arguments to pass to pingouin.linear_regression.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing critical effect size values.
+
+    Raises:
+        ValueError: If variant is not one of "ttest" or "ztest".
+    """
+    if variant not in ["ttest", "ztest"]:
+        raise ValueError("variant must be one of 'ttest' or 'ztest'")
+
+    alpha = utils.get_alpha(confidence, alternative)
+
+    model = pingouin.linear_regression(X=X, y=y, alpha=alpha, **kwargs)
+    coef = model["coef"].values
+
+    coef_critical = critical_for_linear_regression_se_coefficients(
+        se_coefficients=model["se"].values,
+        dof=model.df_resid_,
+        confidence=confidence,
+        alternative=alternative,
+        variant=variant,
+    )
+
+    return pd.DataFrame(
+        {
+            "names": model["names"].values,
+            "coef": coef,
+            "coef_critical": coef_critical,
+        },
+        index=list(range(len(coef))),
+    )