puncc 0.7__tar.gz

puncc-0.7/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.1
+Name: puncc
+Version: 0.7
+Summary: Predictive UNcertainty Calibration and Conformalization Library
+Home-page: https://github.com/deel-ai/puncc
+Author: Mouhcine Mendil, Luca Mossina, Joseba Dalmau
+Author-email: mouhcine.mendil@irt-saintexupery.com, luca.mossina@irt-saintexupery.com, joseba.dalmau@irt-saintexupery.com
+License: UNKNOWN
+Description: <!-- Banner -->
+        <div align="center">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner_dark.png">
+          <source media="(prefers-color-scheme: light)" srcset="docs/assets/banner_light.png">
+          <img src="docs/assets/banner_light.png" alt="Puncc" width="90%" align="right">
+        </picture>
+        </div>
+        <br>
+        
+        <!-- Badges -->
+        <div align="center">
+          <a href="#">
+            <img src="https://img.shields.io/badge/Python-3.8 +-efefef">
+          </a>
+          <a href="#">
+            <img src="https://img.shields.io/badge/License-MIT-efefef">
+          </a>
+          <a href="https://github.com/deel-ai/puncc/actions/workflows/linter.yml">
+            <img alt="PyLint" src="https://github.com/deel-ai/puncc/actions/workflows/linter.yml/badge.svg">
+          </a>
+          <a href="https://github.com/deel-ai/puncc/actions/workflows/tests.yml">
+            <img alt="Tox" src="https://github.com/deel-ai/puncc/actions/workflows/tests.yml/badge.svg">
+          </a>
+        </div>
+        <br>
+        
+        ***Puncc*** (short for **P**redictive **un**certainty **c**alibration and **c**onformalization) is an open-source Python library. It seamlessly integrates a collection of state-of-the-art conformal prediction algorithms and associated techniques for diverse machine learning tasks, including regression, classification and anomaly detection.
+        ***Puncc*** can be used with any predictive model to provide rigorous uncertainty estimations.
+        Under data exchangeability (or *i.i.d*), the generated prediction sets are guaranteed to cover the true outputs within a user-defined error $\alpha$.
+        
+        Documentation is available [**online**](https://deel-ai.github.io/puncc/index.html).
+        
+        ## 📚 Table of contents
+        
+        - [🐾 Installation](#-installation)
+        - [📖 Documentation](#-documentation)
+        - [👨‍🎓 Tutorials](#-tutorials)
+        - [🚀 QuickStart](#-quickstart)
+        - [📚 Citation](#-citation)
+        - [💻 Contributing](#-contributing)
+        - [🙏 Acknowledgments](#-acknowledgments)
+        - [👨‍💻 Creators](#-creators)
+        - [📝 License](#-license)
+        
+        ## 🐾 Installation
+        
+        *puncc* requires a version of python higher than 3.8 and several libraries including Scikit-learn and Numpy. It is recommended to install *puncc* in a virtual environment to not mess with your system's dependencies.
+        
+        You can directly install the library using pip:
+        
+        ```bash
+        pip install git+https://github.com/deel-ai/puncc
+        ```
+        
+        <!--
+        You can alternatively clone the repo and use the makefile to automatically create a virtual environment
+        and install the requirements:
+        
+        * For users:
+        
+        ```bash
+        make install-user
+        ```
+        
+        * For developpers:
+        
+        ```bash
+        make prepare-dev
+        ```
+        -->
+        
+        ## 📖 Documentation
+        
+        For comprehensive documentation, we encourage you to visit the [**official documentation page**](https://deel-ai.github.io/puncc/index.html).
+        
+        ## 👨‍🎓 Tutorials
+        
+        We highly recommand following the introduction tutorials to get familiar with the library and its API:
+        
+        * [**Introduction tutorial**](docs/puncc_intro.ipynb)</font> <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1TC_BM7JaEYtBIq6yuYB5U4cJjeg71Tch) </sub>
+        
+        * [**API tutorial**](docs/api_intro.ipynb) <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1d06qQweM1X1eSrCnixA_MLEZil1vXewj) </sub>
+        
+        You can also familiarize yourself with the architecture of *puncc* to build more efficiently your own conformal prediction methods:
+        
+        * [**Architecture overview**](docs/puncc_architecture.ipynb)
+        
+        ## 🚀 Quickstart
+        
+        Conformal prediction enables to transform point predictions into interval predictions with high probability of coverage. The figure below shows the result of applying the split conformal algorithm on a linear regressor.
+        
+        <figure style="text-align:center">
+        <img src="docs/assets/cp_process.png"/>
+        </figure>
+        
+        Many conformal prediction algorithms can easily be applied using *puncc*.  The code snippet below shows the example of split conformal prediction wrapping a linear model,  done in few lines of code:
+        
+        ```python
+        from sklearn import linear_model
+        from deel.puncc.api.prediction import BasePredictor
+        
+        # Load training data and test data
+        # ...
+        
+        # Instanciate a linear regression model
+        # linear_model = ...
+        
+        
+        # Create a predictor to wrap the linear regression model defined earlier.
+        # This enables interoperability with different ML libraries.
+        # The argument `is_trained` is set to False to tell that the the linear model
+        # needs to be trained before the calibration.
+        lin_reg_predictor =  BasePredictor(linear_model, is_trained=False)
+        
+        # Instanciate the split cp wrapper around the linear predictor.
+        split_cp = SplitCP(lin_reg_predictor)
+        
+        # Fit model (as is_trained` is False) on the fit dataset and
+        # compute the residuals on the calibration dataset.
+        # The fit (resp. calibration) subset is randomly sampled from the training
+        # data and constitutes 80% (resp. 20%) of it (fit_ratio = 80%).
+        split_cp.fit(X_train, y_train, fit_ratio=.8)
+        
+        # The predict returns the output of the linear model y_pred and
+        # the calibrated interval [y_pred_lower, y_pred_upper].
+        y_pred, y_pred_lower, y_pred_upper = split_cp.predict(X_test, alpha=alpha)
+        ```
+        
+        The library provides several metrics (`deel.puncc.metrics`) and plotting capabilities (`deel.puncc.plotting`) to evaluate and visualize the results of a conformal procedure. For a target error rate of $\alpha = 0.1$, the marginal coverage reached in this example on the test set is higher than $90$% (see [Introduction tutorial](docs/puncc_intro.ipynb)):
+        
+        <figure style="text-align:center">
+        <img src="docs/assets/results_quickstart_split_cp_pi.png" alt="90% Prediction Interval with the Split Conformal Prediction Method"/>
+        <div align=center>90% Prediction Interval with Split Conformal Prediction.</div>
+        </figure>
+        <br>
+        
+        ### More flexibility with the API
+        
+        *Puncc* provides two ways of defining and using conformal prediction wrappers:
+        - A direct approach to run state-of-the-art conformal prediction procedures. This is what we used in the previous conformal regression example.
+        - **Low-level API**: a more flexible approach based of full customization of the prediction model, the choice of nonconformity scores and the split between fit and calibration datasets.
+        
+        A quick comparison of both approaches is provided in the [API tutorial](docs/api_intro.ipynb) for a regression problem.
+        
+        ## 📚 Citation
+        
+        If you use our library for your work, please cite our paper:
+        
+        ```
+        @inproceedings{mendil2023puncc,
+          title={PUNCC: a Python Library for Predictive Uncertainty Calibration and Conformalization},
+          author={Mendil, Mouhcine and Mossina, Luca and Vigouroux, David},
+          booktitle={Conformal and Probabilistic Prediction with Applications},
+          pages={582--601},
+          year={2023},
+          organization={PMLR}
+        }
+        ```
+        
+        *Puncc* has been used to support the work presented in our COPA 2022 paper on conformal prediction for time series.
+        
+        ```
+        @inproceedings{mendil2022robust,
+          title={Robust Gas Demand Forecasting With Conformal Prediction},
+          author={Mendil, Mouhcine and Mossina, Luca and Nabhan, Marc and Pasini, Kevin},
+          booktitle={Conformal and Probabilistic Prediction with Applications},
+          pages={169--187},
+          year={2022},
+          organization={PMLR}
+        }
+        ```
+        
+        ## 💻 Contributing
+        
+        Contributions are welcome! Feel free to report an issue or open a pull
+        request. Take a look at our guidelines [here](CONTRIBUTING.md).
+        
+        ## 🙏 Acknowledgments
+        
+        <img align="right" src="https://www.deel.ai/wp-content/uploads/2021/05/logo-DEEL.png" width="25%">
+        This project received funding from the French ”Investing for the Future – PIA3” program within the Artificial and Natural Intelligence Toulouse Institute (ANITI). The authors gratefully acknowledge the support of the <a href="https://www.deel.ai/"> DEEL </a> project.
+        
+        ## 👨‍💻 Creators
+        
+        [Mouhcine MENDIL](https://github.com/M-Mouhcine) initially developed this library as a research tool, with assistance from [Lucas MOSSINA](https://github.com/lmossina). We have recently welcomed [Joseba DALMAU](https://github.com/jdalch) to the team to help enhance **puncc** and work on the development of new features.
+        
+        ## 🔑 License
+        
+        The package is released under [MIT](LICENSES/headers/MIT-Clause.txt) license.
+        
+Platform: UNKNOWN
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: interactive
+Provides-Extra: dev

puncc-0.7/README.md

@@ -0,0 +1,190 @@
+<!-- Banner -->
+<div align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner_dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="docs/assets/banner_light.png">
+  <img src="docs/assets/banner_light.png" alt="Puncc" width="90%" align="right">
+</picture>
+</div>
+<br>
+
+<!-- Badges -->
+<div align="center">
+  <a href="#">
+    <img src="https://img.shields.io/badge/Python-3.8 +-efefef">
+  </a>
+  <a href="#">
+    <img src="https://img.shields.io/badge/License-MIT-efefef">
+  </a>
+  <a href="https://github.com/deel-ai/puncc/actions/workflows/linter.yml">
+    <img alt="PyLint" src="https://github.com/deel-ai/puncc/actions/workflows/linter.yml/badge.svg">
+  </a>
+  <a href="https://github.com/deel-ai/puncc/actions/workflows/tests.yml">
+    <img alt="Tox" src="https://github.com/deel-ai/puncc/actions/workflows/tests.yml/badge.svg">
+  </a>
+</div>
+<br>
+
+***Puncc*** (short for **P**redictive **un**certainty **c**alibration and **c**onformalization) is an open-source Python library. It seamlessly integrates a collection of state-of-the-art conformal prediction algorithms and associated techniques for diverse machine learning tasks, including regression, classification and anomaly detection.
+***Puncc*** can be used with any predictive model to provide rigorous uncertainty estimations.
+Under data exchangeability (or *i.i.d*), the generated prediction sets are guaranteed to cover the true outputs within a user-defined error $\alpha$.
+
+Documentation is available [**online**](https://deel-ai.github.io/puncc/index.html).
+
+## 📚 Table of contents
+
+- [🐾 Installation](#-installation)
+- [📖 Documentation](#-documentation)
+- [👨‍🎓 Tutorials](#-tutorials)
+- [🚀 QuickStart](#-quickstart)
+- [📚 Citation](#-citation)
+- [💻 Contributing](#-contributing)
+- [🙏 Acknowledgments](#-acknowledgments)
+- [👨‍💻 Creators](#-creators)
+- [📝 License](#-license)
+
+## 🐾 Installation
+
+*puncc* requires a version of python higher than 3.8 and several libraries including Scikit-learn and Numpy. It is recommended to install *puncc* in a virtual environment to not mess with your system's dependencies.
+
+You can directly install the library using pip:
+
+```bash
+pip install git+https://github.com/deel-ai/puncc
+```
+
+<!--
+You can alternatively clone the repo and use the makefile to automatically create a virtual environment
+and install the requirements:
+
+* For users:
+
+```bash
+make install-user
+```
+
+* For developpers:
+
+```bash
+make prepare-dev
+```
+-->
+
+## 📖 Documentation
+
+For comprehensive documentation, we encourage you to visit the [**official documentation page**](https://deel-ai.github.io/puncc/index.html).
+
+## 👨‍🎓 Tutorials
+
+We highly recommand following the introduction tutorials to get familiar with the library and its API:
+
+* [**Introduction tutorial**](docs/puncc_intro.ipynb)</font> <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1TC_BM7JaEYtBIq6yuYB5U4cJjeg71Tch) </sub>
+
+* [**API tutorial**](docs/api_intro.ipynb) <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1d06qQweM1X1eSrCnixA_MLEZil1vXewj) </sub>
+
+You can also familiarize yourself with the architecture of *puncc* to build more efficiently your own conformal prediction methods:
+
+* [**Architecture overview**](docs/puncc_architecture.ipynb)
+
+## 🚀 Quickstart
+
+Conformal prediction enables to transform point predictions into interval predictions with high probability of coverage. The figure below shows the result of applying the split conformal algorithm on a linear regressor.
+
+<figure style="text-align:center">
+<img src="docs/assets/cp_process.png"/>
+</figure>
+
+Many conformal prediction algorithms can easily be applied using *puncc*.  The code snippet below shows the example of split conformal prediction wrapping a linear model,  done in few lines of code:
+
+```python
+from sklearn import linear_model
+from deel.puncc.api.prediction import BasePredictor
+
+# Load training data and test data
+# ...
+
+# Instanciate a linear regression model
+# linear_model = ...
+
+
+# Create a predictor to wrap the linear regression model defined earlier.
+# This enables interoperability with different ML libraries.
+# The argument `is_trained` is set to False to tell that the the linear model
+# needs to be trained before the calibration.
+lin_reg_predictor =  BasePredictor(linear_model, is_trained=False)
+
+# Instanciate the split cp wrapper around the linear predictor.
+split_cp = SplitCP(lin_reg_predictor)
+
+# Fit model (as is_trained` is False) on the fit dataset and
+# compute the residuals on the calibration dataset.
+# The fit (resp. calibration) subset is randomly sampled from the training
+# data and constitutes 80% (resp. 20%) of it (fit_ratio = 80%).
+split_cp.fit(X_train, y_train, fit_ratio=.8)
+
+# The predict returns the output of the linear model y_pred and
+# the calibrated interval [y_pred_lower, y_pred_upper].
+y_pred, y_pred_lower, y_pred_upper = split_cp.predict(X_test, alpha=alpha)
+```
+
+The library provides several metrics (`deel.puncc.metrics`) and plotting capabilities (`deel.puncc.plotting`) to evaluate and visualize the results of a conformal procedure. For a target error rate of $\alpha = 0.1$, the marginal coverage reached in this example on the test set is higher than $90$% (see [Introduction tutorial](docs/puncc_intro.ipynb)):
+
+<figure style="text-align:center">
+<img src="docs/assets/results_quickstart_split_cp_pi.png" alt="90% Prediction Interval with the Split Conformal Prediction Method"/>
+<div align=center>90% Prediction Interval with Split Conformal Prediction.</div>
+</figure>
+<br>
+
+### More flexibility with the API
+
+*Puncc* provides two ways of defining and using conformal prediction wrappers:
+- A direct approach to run state-of-the-art conformal prediction procedures. This is what we used in the previous conformal regression example.
+- **Low-level API**: a more flexible approach based of full customization of the prediction model, the choice of nonconformity scores and the split between fit and calibration datasets.
+
+A quick comparison of both approaches is provided in the [API tutorial](docs/api_intro.ipynb) for a regression problem.
+
+## 📚 Citation
+
+If you use our library for your work, please cite our paper:
+
+```
+@inproceedings{mendil2023puncc,
+  title={PUNCC: a Python Library for Predictive Uncertainty Calibration and Conformalization},
+  author={Mendil, Mouhcine and Mossina, Luca and Vigouroux, David},
+  booktitle={Conformal and Probabilistic Prediction with Applications},
+  pages={582--601},
+  year={2023},
+  organization={PMLR}
+}
+```
+
+*Puncc* has been used to support the work presented in our COPA 2022 paper on conformal prediction for time series.
+
+```
+@inproceedings{mendil2022robust,
+  title={Robust Gas Demand Forecasting With Conformal Prediction},
+  author={Mendil, Mouhcine and Mossina, Luca and Nabhan, Marc and Pasini, Kevin},
+  booktitle={Conformal and Probabilistic Prediction with Applications},
+  pages={169--187},
+  year={2022},
+  organization={PMLR}
+}
+```
+
+## 💻 Contributing
+
+Contributions are welcome! Feel free to report an issue or open a pull
+request. Take a look at our guidelines [here](CONTRIBUTING.md).
+
+## 🙏 Acknowledgments
+
+<img align="right" src="https://www.deel.ai/wp-content/uploads/2021/05/logo-DEEL.png" width="25%">
+This project received funding from the French ”Investing for the Future – PIA3” program within the Artificial and Natural Intelligence Toulouse Institute (ANITI). The authors gratefully acknowledge the support of the <a href="https://www.deel.ai/"> DEEL </a> project.
+
+## 👨‍💻 Creators
+
+[Mouhcine MENDIL](https://github.com/M-Mouhcine) initially developed this library as a research tool, with assistance from [Lucas MOSSINA](https://github.com/lmossina). We have recently welcomed [Joseba DALMAU](https://github.com/jdalch) to the team to help enhance **puncc** and work on the development of new features.
+
+## 🔑 License
+
+The package is released under [MIT](LICENSES/headers/MIT-Clause.txt) license.

puncc-0.7/deel/puncc/__init__.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+# Copyright IRT Antoine de Saint Exupéry et Université Paul Sabatier Toulouse III - All
+# rights reserved. DEEL is a research program operated by IVADO, IRT Saint Exupéry,
+# CRIAQ and ANITI - https://www.deel.ai/
+#
+# 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.
+"""Initialization of puncc."""
+import logging.config
+
+
+# Create the Logger
+logging.basicConfig(
+    format="%(asctime)s === %(name)s [%(funcName)s()] | %(levelname)s | - %(message)s",
+    datefmt="%d-%b-%y %H:%M:%S",
+    level=logging.ERROR,
+)
+loggers = logging.getLogger(__name__)

puncc-0.7/deel/puncc/anomaly_detection.py

@@ -0,0 +1,231 @@
+# -*- coding: utf-8 -*-
+# Copyright IRT Antoine de Saint Exupéry et Université Paul Sabatier Toulouse III - All
+# rights reserved. DEEL is a research program operated by IVADO, IRT Saint Exupéry,
+# CRIAQ and ANITI - https://www.deel.ai/
+#
+# 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.
+"""
+This module implements usual anomaly detection wrappers.
+"""
+import logging
+from typing import Iterable
+from typing import Optional
+from typing import Tuple
+
+import numpy as np
+
+from deel.puncc.api.calibration import ScoreCalibrator
+from deel.puncc.api.splitting import IdSplitter
+from deel.puncc.api.splitting import RandomSplitter
+
+logger = logging.getLogger(__name__)
+
+
+class SplitCAD:
+    """Split conformal anomaly detection method based on Laxhammar's algorithm.
+    The anomaly detection is based on the calibrated threshold (through
+    conformal prediction) of underlying anomaly detection (model's) scores.
+    For more details, we refer the user to the :ref:`theory overview
+    page <theory_overview>`.
+
+    :param BasePredictor predictor: a predictor implementing fit and predict.
+    :param bool train: if False, prediction model(s) will not be (re)trained.
+        Defaults to True.
+    :param float random_state: random seed used when the user does not
+        provide a custom fit/calibration split in `fit` method.
+
+    Example::
+
+        import numpy as np
+        from sklearn.ensemble import IsolationForest
+        from sklearn.datasets import make_moons
+        import matplotlib.pyplot as plt
+
+        from deel.puncc.anomaly_detection import SplitCAD
+        from deel.puncc.api.prediction import BasePredictor
+
+        # We generate the two moons dataset
+        dataset = 4 * make_moons(n_samples=1000, noise=0.05, random_state=0)[
+            0
+        ] - np.array([0.5, 0.25])
+
+        # We generate uniformly new (test) data points
+        rng = np.random.RandomState(42)
+        z_test = rng.uniform(low=-6, high=6, size=(150, 2))
+
+
+        # The nonconformity scores are defined as the IF scores (anomaly score).
+        # By default, score_samples return the opposite of IF scores.
+        # We need to redefine the predict to output the nonconformity scores.
+        class ADPredictor(BasePredictor):
+            def predict(self, X):
+                return -self.model.score_samples(X)
+
+        # Instantiate the Isolation Forest (IF) anomaly detection model
+        # and wrap it in a predictor
+        if_predictor = ADPredictor(IsolationForest(random_state=42))
+
+        # Instantiate CAD on top of IF predictor
+        if_cad = SplitCAD(if_predictor, train=True, random_state=0)
+
+        # Fit the IF on the proper fitting dataset and
+        # calibrate it using calibration dataset.
+        # The two datasets are sampled randomly with a ration of 7:3,
+        # respectively.
+        if_cad.fit(z=dataset, fit_ratio=0.7)
+
+        # We set the maximum false detection rate to 1%
+        alpha = 0.01
+
+        # The method `predict` is called on the new data points
+        # to test which are anomalous and which are not
+        results = if_cad.predict(z_test, alpha=alpha)
+
+        anomalies = z_test[results]
+        not_anomalies = z_test[np.invert(results)]
+
+        # Plot results
+        plt.scatter(dataset[:, 0], dataset[:, 1], s=10, label="Inliers")
+        plt.scatter(
+            anomalies[:, 0],
+            anomalies[:, 1],
+            marker="x",
+            color="red",
+            s=40,
+            label="Anomalies",
+        )
+        plt.scatter(
+            not_anomalies[:, 0],
+            not_anomalies[:, 1],
+            marker="x",
+            color="blue",
+            s=40,
+            label="Normal",
+        )
+        plt.xticks(())
+        plt.yticks(())
+        plt.legend()
+    """
+
+    def __init__(self, predictor, *, train=True, random_state: float = None):
+        self.predictor = predictor
+        self.calibrator = ScoreCalibrator(nonconf_score_func=predictor.predict)
+
+        self.train = train
+
+        self.random_state = random_state
+
+        self.__is_fit = False
+
+    def fit(
+        self,
+        *,
+        z: Optional[Iterable] = None,
+        fit_ratio: float = 0.8,
+        z_fit: Optional[Iterable] = None,
+        z_calib: Optional[Iterable] = None,
+        **kwargs: Optional[dict],
+    ):
+        """This method fits the models on the fit data
+        and computes nonconformity scores on calibration data.
+        If z are provided, randomly split data into
+        fit and calib subsets w.r.t to the fit_ratio.
+        In case z_fit and z_calib are provided,
+        the conformalization is performed on the given user defined
+        fit and calibration sets.
+
+        .. NOTE::
+
+            If z is provided, `fit` ignores
+            any user-defined fit/calib split.
+
+
+        :param Iterable z: data points from the training dataset.
+        :param float fit_ratio: the proportion of samples assigned to the
+            fit subset.
+        :param Iterable z_fit: data points from the fit dataset.
+        :param Iterable z_calib: data points from the calibration dataset.
+        :param dict kwargs: predict configuration to be passed to the model's
+            fit method.
+
+        :raises RuntimeError: no dataset provided.
+
+        """
+
+        if z is not None:
+            splitter = RandomSplitter(
+                ratio=fit_ratio, random_state=self.random_state
+            )
+
+        elif z_fit is not None and z_calib is not None:
+            splitter = IdSplitter(z_fit, z_fit, z_calib, z_calib)
+
+        elif (
+            self.predictor.is_trained and z_fit is None and z_calib is not None
+        ):
+            splitter = IdSplitter(
+                np.empty_like(z_calib), np.empty_like(z_calib), z_calib, z_calib
+            )
+
+        else:
+            raise RuntimeError("No dataset provided.")
+
+        # Apply splitter
+        z_fit, _, z_calib, _ = splitter(z, z)[0]
+
+        # Fit underlying model and calibrator
+        if self.train:
+            logger.info("Fitting model")
+            self.predictor.fit(z_fit, **kwargs)
+
+        # Make sure that predictor is already trained if train arg is False
+        elif self.train is False and self.predictor.is_trained is False:
+            raise RuntimeError(
+                "'train' argument is set to 'False' but model is not pre-trained"
+            )
+
+        else:  # Skipping training
+            logger.info("Skipping training.")
+
+        # Fitting calibrator
+        self.calibrator.fit(z_calib)
+
+        self.__is_fit = True
+
+    def predict(self, z_test: Iterable, alpha) -> Tuple[np.ndarray]:
+        """Predict whether each example is an anomaly or not. The decision is
+        taken based on the calibrated threshold (through conformal prediction)
+        of underlying anomaly detection scores.
+
+        :param Iterable z_test: new data points.
+        :param float alpha: target maximum FDR.
+
+        :returns: outlier tag. True if outlier, False otherwise.
+        :rtype: Iterables[bool]
+
+        """
+
+        if self.__is_fit is None:
+            raise RuntimeError("Fit method should be called before predict.")
+
+        anomaly_pred = np.invert(
+            self.calibrator.is_conformal(z_test, alpha=alpha)
+        )
+
+        return anomaly_pred

puncc-0.7/deel/puncc/api/__init__.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+# Copyright IRT Antoine de Saint Exupéry et Université Paul Sabatier Toulouse III - All
+# rights reserved. DEEL is a research program operated by IVADO, IRT Saint Exupéry,
+# CRIAQ and ANITI - https://www.deel.ai/
+#
+# 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.