Metadata-Version: 2.1
Name: diff-binom-confint
Version: 0.0.9
Summary: Computation of confidence intervals for binomial proportions and for difference of binomial proportions.
Home-page: https://github.com/DeepPSP/DBCI
Author: DeepPSP
Author-email: wenh06@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: deprecate-kwargs
Requires-Dist: Deprecated
Requires-Dist: dataclasses
Requires-Dist: typing-extensions
Provides-Extra: acc
Requires-Dist: numba ; extra == 'acc'
Provides-Extra: dev
Requires-Dist: pandas ; extra == 'dev'
Requires-Dist: black (==22.3.0) ; extra == 'dev'
Requires-Dist: flake8 ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-xdist ; extra == 'dev'
Requires-Dist: numba ; extra == 'dev'
Provides-Extra: test
Requires-Dist: pandas ; extra == 'test'
Requires-Dist: black (==22.3.0) ; extra == 'test'
Requires-Dist: flake8 ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-xdist ; extra == 'test'

# Confidence Intervals for Difference of Binomial Proportions

![pytest](https://github.com/DeepPSP/DBCI/actions/workflows/run-pytest.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/diff-binom-confint?style=flat-square)
![downloads](https://img.shields.io/pypi/dm/diff-binom-confint?style=flat-square)
![license](https://img.shields.io/github/license/DeepPSP/DBCI?style=flat-square)

Computation of confidence intervals for binomial proportions and for difference of binomial proportions.

## Installation

Run

```bash
python -m pip install diff-binom-confint
```

or install the latest version in [GitHub](https://github.com/DeepPSP/DBCI/) using

```bash
python -m pip install git+https://github.com/DeepPSP/DBCI.git
```

or git clone this repository and install locally via

```bash
cd DBCI
python -m pip install .
```

## `Numba` accelerated version

Install using

```bash
python -m pip install diff-binom-confint[acc]
```

## Usage examples

```python
from diff_binom_confint import compute_difference_confidence_interval

n_positive, n_total = 84, 101
ref_positive, ref_total = 89, 105

confint = compute_difference_confidence_interval(
    n_positive,
    n_total,
    ref_positive,
    ref_total,
    conf_level=0.95,
    method="wilson",
)
```

## Implemented methods

### Confidence intervals for binomial proportions

<details>
<summary>Click to view!</summary>

|   Method (type)   | Implemented        |
|-------------------|--------------------|
| wilson            | :heavy_check_mark: |
| wilson-cc         | :heavy_check_mark: |
| wald              | :heavy_check_mark: |
| wald-cc           | :heavy_check_mark: |
| agresti-coull     | :heavy_check_mark: |
| jeffreys          | :heavy_check_mark: |
| clopper-pearson   | :heavy_check_mark: |
| arcsine           | :heavy_check_mark: |
| logit             | :heavy_check_mark: |
| pratt             | :heavy_check_mark: |
| witting           | :heavy_check_mark: |
| mid-p             | :heavy_check_mark: |
| lik               | :heavy_check_mark: |
| blaker            | :heavy_check_mark: |
| modified-wilson   | :heavy_check_mark: |
| modified-jeffreys | :heavy_check_mark: |

</details>

### Confidence intervals for difference of binomial proportions

<details>
<summary>Click to view!</summary>

|   Method (type)             | Implemented        |
|-----------------------------|--------------------|
| wilson                      | :heavy_check_mark: |
| wilson-cc                   | :heavy_check_mark: |
| wald                        | :heavy_check_mark: |
| wald-cc                     | :heavy_check_mark: |
| haldane                     | :heavy_check_mark: |
| jeffreys-perks              | :heavy_check_mark: |
| mee                         | :heavy_check_mark: |
| miettinen-nurminen          | :heavy_check_mark: |
| true-profile                | :heavy_check_mark: |
| hauck-anderson              | :heavy_check_mark: |
| agresti-caffo               | :heavy_check_mark: |
| brown-li                    | :heavy_check_mark: |
| brown-li-jeffrey            | :heavy_check_mark: |
| miettinen-nurminen-brown-li | :heavy_check_mark: |
| exact                       | :x:                |
| mid-p                       | :x:                |
| santner-snell               | :x:                |
| chan-zhang                  | :x:                |
| agresti-min                 | :x:                |
| wang                        | :x:                |
| pradhan-banerjee            | :x:                |

</details>

## References

1. <a name="ref1"></a> [SAS](https://www.lexjansen.com/wuss/2016/127_Final_Paper_PDF.pdf)
2. <a name="ref2"></a> [PASS](https://ncss-wpengine.netdna-ssl.com/wp-content/themes/ncss/pdf/Procedures/PASS/Confidence_Intervals_for_the_Difference_Between_Two_Proportions.pdf)
3. <a name="ref3"></a> [statsmodels.stats.proportion](https://www.statsmodels.org/devel/_modules/statsmodels/stats/proportion.html)
4. <a name="ref4"></a> [scipy.stats._binomtest](https://github.com/scipy/scipy/blob/main/scipy/stats/_binomtest.py)
5. <a name="ref5"></a> [corplingstats](https://corplingstats.wordpress.com/2019/04/27/correcting-for-continuity/)
6. <a name="ref6"></a> [DescTools.StatsAndCIs](https://github.com/AndriSignorell/DescTools/blob/master/R/StatsAndCIs.r)
7. <a name="ref7"></a> [Newcombee](https://onlinelibrary.wiley.com/doi/10.1002/(SICI)1097-0258(19980430)17:8%3C873::AID-SIM779%3E3.0.CO;2-I)

## NOTE

[Reference 1](#ref1) has errors in the description of the methods `Wilson CC`, `Mee`, `Miettinen-Nurminen`.
The correct computation of `Wilson CC` is given in [Reference 5](#ref5).
The correct computation of `Mee`, `Miettinen-Nurminen` are given in the **code blocks** in [Reference 1](#ref1)

## Test data

[Test data](test/test-data/) are

1. taken (with slight modification, e.g. the `upper_bound` of `miettinen-nurminen-brown-li` method in the [edge case file](test/test-data/example-10-10-vs-0-20.csv)) from [Reference 1](#ref1) for automatic test of the correctness of the implementation of the algorithms.
2. generated using [DescTools.StatsAndCIs](#ref6) via

    ```R
    library("DescTools")
    library("data.table")

    results = data.table()
    for (m in c("wilson", "wald", "waldcc", "agresti-coull", "jeffreys",
                    "modified wilson", "wilsoncc","modified jeffreys",
                    "clopper-pearson", "arcsine", "logit", "witting", "pratt", 
                    "midp", "lik", "blaker")){
        ci = BinomCI(84,101,method = m)
        new_row = data.table("method" = m, "ratio"=ci[1], "lower_bound" = ci[2], "upper_bound" = ci[3])
        results = rbindlist(list(results, new_row))
    }
    fwrite(results, "./test/test-data/example-84-101.csv")  # with manual slight adjustment of method names
    ```

3. taken from [Reference 7](#ref7) (Table II).

The filenames has the following pattern:

```python
# for computing confidence interval for difference of binomial proportions
"example-(?P<n_positive>[\\d]+)-(?P<n_total>[\\d]+)-vs-(?P<ref_positive>[\\d]+)-(?P<ref_total>[\\d]+)\\.csv"

# for computing confidence interval for binomial proportions
"example-(?P<n_positive>[\\d]+)-(?P<n_total>[\\d]+)\\.csv"
```

Note that the out-of-range values (e.g. `> 1`) are left as empty values in the `.csv` files.

## Known Issues

1. Edge cases incorrect for the method `true-profile`.


