Metadata-Version: 2.1
Name: pythresh
Version: 0.1.9
Summary: A Python Toolbox for Outlier Detection Thresholding
Home-page: https://github.com/KulikDM/pythresh
Author: D Kulik
License: UNKNOWN
Download-URL: https://github.com/KulikDM/pythresh/archive/master.zip
Keywords: outlier detection,anomaly detection,outlier ensembles,thresholding,cutoff
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Description-Content-Type: text/x-rst
License-File: LICENSE

Python Outlier Detection Thresholding (PyThresh)
================================================

**Deployment, Stats, & License**

.. image:: https://img.shields.io/pypi/v/pythresh.svg?color=brightgreen&logo=pypi&logoColor=white
   :target: https://pypi.org/project/pythresh/
   :alt: PyPI version

.. image:: https://img.shields.io/github/stars/KulikDM/pythresh.svg?logo=github&logoColor=white
   :target: https://github.com/KulikDM/pythresh/stargazers
   :alt: GitHub stars


.. image:: https://img.shields.io/github/forks/KulikDM/pythresh.svg?color=blue&logo=github&logoColor=white
   :target: https://github.com/KulikDM/pythresh/network
   :alt: GitHub forks


.. image:: https://pepy.tech/badge/pythresh?
   :target: https://pepy.tech/project/pythresh
   :alt: Downloads
   
  
.. image:: https://img.shields.io/pypi/pyversions/pythresh.svg?logo=python&logoColor=white
   :target: https://pypi.org/project/pythresh/
   :alt: Python versions
  

.. image:: https://img.shields.io/github/license/KulikDM/pythresh.svg
   :target: https://github.com/KulikDM/pythresh/blob/master/LICENSE
   :alt: License


-----

PyThresh is a comprehensive and scalable **Python toolkit** for **thresholding outlier detection scores** in univariate/multivariate data. It has been writen to work in tandem with PyOD with similar syntax and data structures. However, it is not limited to this single library to achieve good results. PyThresh is meant to threshold scores generated by an outlier detection. It thresholds scores without the need to set a contamination level or have the user guess the amount of outliers that may exist in the dataset beforehand. These non-parametric methods were written to reduce the user's input/guess work and rely on statistics instead to threshold outlier scores. The scores needed to apply thresholing correctly must follow these rules: the higher the score, the higher the probability that it is an outlier in the dataset. All threshold functions return a binary array where 0 values represent inliers, while 1 values are outliers. 

PyThresh includes more than 30 thresholding algorithms. These algorithms range from using simple statistical analysis like the Z-score to more complex mathematical methods that involve graph theory and topology. 


**Outlier Detection Thresholding with 7 Lines of Code**\ :


.. code-block:: python


    # train the KNN detector
    from pyod.models.knn import KNN
    from pythresh.thresholds.dsn import DSN
    
    clf = KNN()
    clf.fit(X_train)

    # get outlier scores
    decision_scores = clf.decision_scores_  # raw outlier scores on the train data
    
    # get outlier labels 
    thres = DSN()
    labels = thres.eval(decision_scores)
    

Installation
^^^^^^^^^^^^

It is recommended to use **pip** for installation:

.. code-block:: bash

   pip install pythresh            # normal install
   pip install --upgrade pythresh  # or update if needed

Alternatively, you could clone and run setup.py file:

.. code-block:: bash

   git clone https://github.com/KulikDM/pythresh
   cd pythresh
   pip install .


**Required Dependencies**\ :


* matplotlib
* numpy>=1.13
* scipy>=1.3.1
* scikit_learn>=0.20.0
* six
* pyod


API Cheatsheet
^^^^^^^^^^^^^^


* **eval(score)**\ : evaluate outlier score.

Key Attributes of threshold:


* **thresh_**\ : Return the threshold value that seperates inliers from outliers. Outliers are considered all values above this threshold value. Note the threshold value has been derived from normalized scores.

Implemented Algorithms
^^^^^^^^^^^^^^^^^^^^^^

**(i) Individual Thresholding Algorithms** :

===================== ================================================================ ==============================================================================
Abbr                  Description                                                      Parameters    
===================== ================================================================ ==============================================================================
AUCP                  Area Under Curve Precentage [#aucp1]_            		       None
BOOT                  Bootstrapping [#boot1]_            			       None
CHAU		      Chauvenet's Criterion [#chau1]_     			       method: [default='mean', 'median', 'gmean']
CLF		      Trained Classifier [#clf1]_        			       None
DSN		      Distance Shift from Normal [#dsn1]_        		       metric: [default = 'JS':  Jensen-Shannon, 'WS':  Wasserstein, 'ENG': Energy, 'BHT': Bhattacharyya, 'HLL': Hellinger, 'HI':  Histogram intersection, 'LK':  Lukaszyk–Karmowski metric for normal distributions, 'LP':  Levy-Prokhorov, 'MAH': Mahalanobis, 'TMT': Tanimoto, 'RES': Studentized residual distance]
EB		      Elliptical Boundary [#eb1]_       			       None
FGD		      Fixed Gradient Descent [#fgd1]_            		       None
FILTER                Filtering Based [#filter1]_                                      method: ['gaussian', 'savgol', 'hilbert', default = 'wiener', 'medfilt', 'decimate', 'detrend', 'resample']; sigma: int, default='native'
FWFM		      Full Width at Full Minimum [#fwfm1]_        		       None
GESD		      Generalized Extreme Studentized Deviate  [#gesd1]_               max_outliers: int, default='native'; alpha: float, default=0.05 
HIST		      Histogram Based [#hist1]_           			       n_bins: int, default='native', method: [default='otsu', 'yen', 'isodata', 'li', 'minimum', 'triangle']
IQR		      Inter-Qaurtile Region [#iqr1]_		                       None
KARCH                 Karcher mean (Riemannian Center of Mass) [#karch1]_              ndim: int, default = 2; method: ['simple', default = 'complex']
KMEANS		      K-means Clustering [#kmeans1]_                     	       None
MAD		      Median Absolute Deviation [#mad1]_			       None
MCST		      Monte Carlo Shapiro Tests	[#mcst1]_		               None
MOLL		      Friedrichs' Mollifier [#moll1]_ [#moll2]_			       None
MTT		      Modified Thompson Tau Test [#mtt1]_			       strictness: [1,2,3,default=4,5]
QMCD                  Quasi-Monte Carlo Discreprancy [#qmcd1]_		               method: ['CD', default='WD', 'MD', 'L2-star'], lim: ['Q', default='P']
REGR		      Regression Based [#regr1]_      				       method: [default='siegel', 'theil']
SHIFT		      Mean Shift Clustering [#shift1]_			       	       None
WIND		      Topological Winding Number [#wind1]_    			       None
YJ		      Yeo-Johnson Transformation [#yj1]_			       None
ZSCORE		      Z-score [#zscore1]_					       None
ALL                   All Thresholders Combined                                        thresholders: list, default='all'; max_contam: float, default=0.5; method: [default='mean', 'median', 'gmean']
===================== ================================================================ ==============================================================================

Implementations & Benchmarks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**The comparison among implemented models and general implementation** is made available below

For Jupyter Notebooks, please navigate to `notebooks <https://github.com/KulikDM/pythresh/tree/main/notebooks>`_.

A quick look at all the thresholders performance can be found at **"/notebooks/Compare All Models.ipynb"**

.. image:: https://raw.githubusercontent.com/KulikDM/pythresh/main/imgs/All.png
   :target: https://raw.githubusercontent.com/KulikDM/pythresh/main/imgs/All.png
   :alt: Comparision_of_All
   
   
References
^^^^^^^^^^

**Please Note** not all references' exact methods have been employed in PyThresh. Rather, the references serve to demonstrate the validity of the threshold types available in PyThresh. 

.. [#aucp1] `A Robust AUC Maximization Framework With Simultaneous Outlier Detection and Feature Selection for Positive-Unlabeled Classification <https://arxiv.org/abs/1803.06604>`_

.. [#boot1] `An evaluation of bootstrap methods for outlier detection in least squares regression <https://www.researchgate.net/publication/24083638_An_evaluation_of_bootstrap_methods_for_outlier_detection_in_least_squares_regression>`_

.. [#chau1] `Chauvenet's and Peirce's Criterion <https://www.researchgate.net/publication/299829851_Chauvenet%27s_and_Peirce%27s_Criterion_literature_review>`_

.. [#clf1] `Linear Models for Outlier Detection <https://link.springer.com/chapter/10.1007/978-3-319-47578-3_3>`_

.. [#dsn1] `Fast and Exact Outlier Detection in Metric Spaces: A Proximity Graph-based Approach <https://arxiv.org/abs/2110.08959>`_

.. [#eb1] `Elliptical Insights: Understanding Statistical Methods through Elliptical Geometry <https://arxiv.org/abs/1302.4881>`_

.. [#fgd1] `Iterative gradient descent for outlier detection <https://www.worldscientific.com/doi/10.1142/S0219691321500041>`_

.. [#filter1] `Fitting, Filtering and Analysis: Feature Extraction in Dimensional Metrology Applications <https://digitalmetrology.com/Papers/IDW2002-Abstract.pdf>`_

.. [#fwfm1] `Sparse Auto-Regressive: Robust Estimation of AR Parameters <https://arxiv.org/abs/1306.3317>`_

.. [#gesd1] `An adjusted Grubbs' and generalized extreme studentized deviation <https://www.degruyter.com/document/doi/10.1515/dema-2021-0041/html?lang=en>`_

.. [#hist1] `Effective Histogram Thresholding Techniques for Natural Images Using Segmentation <http://www.joig.net/uploadfile/2015/0116/20150116042320548.pdf>`_

.. [#iqr1] `A new non-parametric detector of univariate outliers for distributions with unbounded support <https://arxiv.org/abs/1509.02473>`_

.. [#karch1] `Riemannian center of mass and mollifier smoothing <https://www.jstor.org/stable/41059320>`_

.. [#kmeans1] `Outlier Detection and Removal Algorithm in K-Means and Hierarchical Clustering <https://www.researchgate.net/publication/319395842_Outlier_Detection_and_Removal_Algorithm_in_K-Means_and_Hierarchical_Clustering>`_

.. [#mad1] `Periodicity Detection of Outlier Sequences Using Constraint Based Pattern Tree with MAD <https://arxiv.org/abs/1507.01685>`_

.. [#mcst1] `Testing normality in the presence of outliers <https://www.researchgate.net/publication/24065017_Testing_normality_in_the_presence_of_outliers>`_

.. [#moll1] `Riemannian center of mass and mollifier smoothing <https://www.jstor.org/stable/41059320>`_

.. [#moll2] `Using the mollifier method to characterize datasets and models: The case of the Universal Soil Loss Equation <https://www.researchgate.net/publication/286670128_Using_the_mollifier_method_to_characterize_datasets_and_models_The_case_of_the_Universal_Soil_Loss_Equation>`_

.. [#mtt1] `Towards a More Reliable Interpretation of Machine Learning Outputs for Safety-Critical Systems using Feature Importance Fusion <https://arxiv.org/abs/2009.05501>`_

.. [#qmcd1] `Deterministic and quasi-random sampling of optimized Gaussian mixture distributions for vibronic Monte Carlo <https://arxiv.org/abs/1912.11594>`_

.. [#regr1] `Linear Models for Outlier Detection <https://link.springer.com/chapter/10.1007/978-3-319-47578-3_3>`_

.. [#shift1] `Mean-shift outlier detection and filtering <https://www.sciencedirect.com/science/article/pii/S0031320321000613>`_

.. [#wind1] `Robust Inside-Outside Segmentation Using Generalized Winding Numbers <https://www.researchgate.net/publication/262165781_Robust_Inside-Outside_Segmentation_Using_Generalized_Winding_Numbers>`_

.. [#yj1] `Transforming variables to central normality <https://arxiv.org/abs/2005.07946>`_

.. [#zscore1] `Multiple outlier detection tests for parametric models <https://arxiv.org/abs/1910.10426>`_


