Merge branch 'develop' into main

README.md

@@ -14,54 +14,80 @@
 <!--Read-the-docs not required for such a small project-->
 
 
-This Python package provides tools to compute and visualize [ROC curves](https://en.wikipedia.org/wiki/Receiver_operating_characteristic). ROC curves can be used to graphically assess the diagnostic ability of binary classifiers. 
+This Python package provides tools to compute and visualize [ROC curves](https://en.wikipedia.org/wiki/Receiver_operating_characteristic), which are used to graphically assess the diagnostic ability of binary classifiers. 
+
+
+Use [`roc_utils`](https://github.com/hirsch-lab/roc-utils) to perform ROC analyses, including the calculation of the ROC-AUC (the area under the ROC curve) and the identification of optimal classification thresholds for different objective functions. In addition, it is possible to compute mean, tolerance interval (TI) and confidence interval (CI) for a set of (related) ROC curves. Finally, error bounds can be estimated and visualized by means of boostrap sampling.
+
+![Exemplary plots generated with `roc_utils`](data/plots-small.png)
 
 
 ### Installation:
 
     pip install roc-utils
 
-To quickly test the installation, use the following cals
+Use the following commands for a quick verification of the installation.
 
     python -c "import roc_utils; print(roc_utils.__version__)"
     python -c "import roc_utils; roc_utils.demo_bootstrap()"
 
+
 ### Usage:
 
+See [examples/tutorial.ipynb](https://github.com/hirsch-lab/roc-utils/blob/main/examples/tutorial.ipynb) for step-by-step introduction.
+
 ```python
 import numpy as np
 import matplotlib.pyplot as plt
-from roc_utils import *
-
-def sample_data(n1, mu1, std1, n2, mu2, std2, seed=42):
-    rng = np.random.RandomState(seed)
-    #  sample size, mean, std
-    x1 = rng.normal(mu1, std1, n1)
-    x2 = rng.normal(mu2, std2, n2)
-    y1 = np.zeros(n1, dtype=bool)
-    y2 = np.ones(n2, dtype=bool)
-    x = np.concatenate([x1,x2])
-    y = np.concatenate([y1,y2])
-    return x, y
-
-x, y = sample_data(n1=300, mu1=0.0, std1=0.5,
-                   n2=300, mu2=1.0, std2=0.7)
+import roc_utils as ru
+
+# Construct a binary classification problem
+x, y = ru.demo_sample_data(n1=300, mu1=0.0, std1=0.5,
+                           n2=300, mu2=1.0, std2=0.7)
+
+# Compute the ROC curve...
 pos_label = True
-roc = compute_roc(X=x, y=y, pos_label=pos_label)
-plot_roc(roc, label="Sample data", color="red")
+roc = ru.compute_roc(X=x, y=y, pos_label=pos_label)
+
+# ...and visualize it
+ru.plot_roc(roc, label="Sample data", color="red")
+plt.show()
+
+# To perform a ROC analysis using bootstrapping
+n_samples = 20
+ru.plot_roc_bootstrap(X=x, y=y, pos_label=pos_label,
+                      n_bootstrap=n_samples,
+                      title="Bootstrap demo");
 plt.show()
 ```
 
-See [examples/tutorial.ipynb](https://github.com/hirsch-lab/roc-utils/blob/main/examples/tutorial.ipynb) for a more detailed introduction.
 
-### Build
+### Build from source:
 
-To build the package, use the following
+To fetch the project and run the tests or examples:
 
 ```bash
 git clone https://github.com/hirsch-lab/roc-utils.git
 cd roc-utils
-python setup.py sdist bdist_wheel
 python tests/test_all.py
 python examples/examples.py
 ```
+
+To create distribution packages (a source archive and a wheel):
+
+```bash 
+python setup.py sdist bdist_wheel
+```
+
+To install the newly created Python package from the source archive:
+
+```bash
+pip uninstall roc-utils
+pip cache remove roc_utils
+pip install dist/roc_utils*.tar.gz
+
+# Verify installation
+python -c "import roc_utils; print(roc_utils.__version__)"
+python -c "import roc_utils; roc_utils.demo_bootstrap()"
+```
+

VERSION

@@ -1 +1 @@
-0.2.0
+0.2.2

roc_utils/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 __author__ = "Norman Juchler"
 
 from ._roc import (get_objective,
@@ -10,4 +10,5 @@
                     plot_roc_simple,
                     plot_roc_bootstrap)
 from ._demo import (demo_basic,
-                    demo_bootstrap)
+                    demo_bootstrap,
+                    demo_sample_data)

roc_utils/_demo.py

@@ -3,7 +3,7 @@
 from ._roc import compute_roc
 
 
-def _sample_data(n1, mu1, std1, n2, mu2, std2, seed=42):
+def demo_sample_data(n1, mu1, std1, n2, mu2, std2, seed=42):
     """
     Construct binary classification problem with n1 and n2
     samples per class, respectively.
@@ -27,9 +27,9 @@ def demo_basic(n_samples=600, seed=42):
     """
     import matplotlib.pyplot as plt
     pos_label = True
-    x, y = _sample_data(n1=n_samples//2, mu1=0.0, std1=0.5,
-                        n2=n_samples//2, mu2=1.0, std2=0.7,
-                        seed=seed)
+    x, y = demo_sample_data(n1=n_samples//2, mu1=0.0, std1=0.5,
+                            n2=n_samples//2, mu2=1.0, std2=0.7,
+                            seed=seed)
     roc = compute_roc(X=x, y=y, pos_label=pos_label)
     plot_roc(roc, label="Dataset", color="red")
     plt.title("Basic demo")
@@ -43,9 +43,9 @@ def demo_bootstrap(n_samples=600, n_bootstrap=50, seed=42):
     import matplotlib.pyplot as plt
     assert(n_samples > 2)
     pos_label = True
-    x, y = _sample_data(n1=n_samples//2, mu1=0.0, std1=0.5,
-                        n2=n_samples//2, mu2=1.0, std2=0.7,
-                        seed=seed)
+    x, y = demo_sample_data(n1=n_samples//2, mu1=0.0, std1=0.5,
+                            n2=n_samples//2, mu2=1.0, std2=0.7,
+                            seed=seed)
     plot_roc_bootstrap(X=x, y=y, pos_label=pos_label,
                        n_bootstrap=n_bootstrap,
                        random_state=seed+1,