cherrypick-ml 0.1.0__py3-none-any.whl

cherrypick/__init__.py

@@ -0,0 +1,4 @@
+from .orchestrator import Orchestrator
+from . import explain, preprocessing, anomaly, splits
+
+__all__ = ['Orchestrator']

cherrypick/anomaly.py

@@ -0,0 +1,120 @@
+import pandas as pd
+import numpy as np
+from scipy.stats import zscore
+from sklearn.ensemble import IsolationForest
+from sklearn.neighbors import LocalOutlierFactor
+from typing import Literal
+
+import warnings as war
+war.filterwarnings('ignore')
+
+class OutlierPruner:
+    """
+    OutlierPruner provides statistical and ML-based methods
+    for detecting and removing outliers from a dataset.
+
+    Parameters
+    ----------
+    method : {'iqr', 'zscore', 'mod_zscore', 'isoforest', 'lof'}
+        Method used for outlier detection.
+
+        - `'iqr'`         - Interquartile Range method
+        - `'zscore'`      - Standard Z-score normalization
+        - `'mod_zscore'`  - Modified Z-score:
+
+                        `modified_Zscore = 0.6745 * (X - median) / MAD`
+
+                        *Where,* 
+                        **median** = *median of the sample data*
+                        **MAD** = *median absolute deviation*
+                        **X** = *sample data points(Xi)*
+        - `'isoforest'`   - Isolation Forest, an ensemble-based anomaly detection method
+        - `'lof'`         - Local Outlier Factor, detects outliers using local density
+
+    df : pandas.DataFrame
+        Input dataset on which outlier pruning will be applied.
+
+    col : str
+        Column name used for outlier detection in statistical methods.
+
+    Notes
+    -----
+    - Statistical methods require a specific column (``col``).
+    - ML-based methods (Isolation Forest, Local Outlier Factor) operate on numerical features.
+    - Modified Z-score is robust to extreme values as it uses the median instead of mean.
+    """
+
+    def __init__(self, method: Literal['iqr', 'zscore', 'mod_zscore', 'isoforest', 'lof'], df:pd.DataFrame, col:str):
+        self.df = df
+        self.col = col
+        self.method = method
+        
+    
+    def __iqr(self):
+            
+                Q1 = self.df[self.col].quantile(0.25)
+                Q3 = self.df[self.col].quantile(0.75)
+                IQR = Q3 - Q1
+
+                lower_fence = Q1 - 1.5 * IQR
+                upper_fence = Q3 + 1.5 * IQR
+
+                return  self.df[(self.df[self.col] >= lower_fence) & (self.df[self.col] <= upper_fence)]   
+            
+    def __zscore(self):
+            z = zscore(self.df[self.col])
+            return self.df[np.abs(z) < 3]
+
+    def __isoforest(self):
+            isolate = IsolationForest(contamination=0.3, n_jobs=-1, random_state=42)
+            
+            X = self.df.select_dtypes(include=np.number)
+            labels_ = isolate.fit_predict(X)
+
+            # outliers = np.where(labels_ == -1)[0]
+            return self.df.iloc[labels_!= -1]
+    
+    def __lof(self):
+            lof = LocalOutlierFactor(n_jobs=-1, n_neighbors=20, algorithm='kd_tree')
+            X = self.df.select_dtypes(include = np.number)
+            labels = lof.fit_predict(X)
+
+            return self.df.iloc[labels != -1]
+            
+
+    def __modded_zscore(self):
+        
+        df1=self.df
+        median = np.median(df1[self.col])
+        mad = np.median(np.abs(df1[self.col] - median))
+        ## If MAD value == 0, then it will return original DataFrame instead of garbage value and prevent division by zero error
+        if mad  == 0 :
+              return self.df
+        
+        mod_zscore = 0.6745 * (df1[self.col] - median)/mad
+
+        normal_data = df1[mod_zscore.abs() < 3]
+        outliers = df1[mod_zscore.abs() > 3]     
+        
+        return normal_data
+
+
+    def remove_outlier(self):
+        '''
+        Calling this function will transform dataset with configuration provided to **OutlierPruner**. 
+        '''
+        try:                
+            METHOD_CONFIG = { 
+                "iqr" : self.__iqr,
+                "zscore" : self.__zscore,
+                "mod_zscore":self.__modded_zscore,
+                "isoforest" : self.__isoforest,
+                "lof" : self.__lof
+            }
+
+            return METHOD_CONFIG[self.method]()
+            
+        except KeyError:
+            raise ValueError(f"Provide an appropriate method : {self.method}") 
+        except Exception as err:
+              raise ValueError(err)

cherrypick/explain.py

@@ -0,0 +1,178 @@
+import shap
+import numpy as np
+import pandas as pd 
+import matplotlib.pyplot as plt
+from sklearn import tree
+from cherrypick.orchestrator import Orchestrator
+from typing import Literal
+
+
+def explainer(model, data, impact_type :Literal['pos', 'neg', 'all'] = 'all'):
+    """
+    Compute SHAP-based feature importance and return sorted impact values.
+
+    This function uses SHAP's TreeExplainer to calculate feature contributions
+    for a given model and dataset. It aggregates SHAP values across samples
+    and (if applicable) across multiple classes, returning feature importance
+    based on absolute SHAP magnitudes.
+
+    Parameters
+    ----------
+    model : object
+        A trained tree-based model compatible with shap.TreeExplainer
+        (e.g., XGBoost, LightGBM, RandomForest).
+
+    data : pandas.DataFrame
+        Input dataset for which SHAP values are to be computed.
+        Must contain only feature columns (no target column).
+
+    impact_type : {'pos', 'neg', 'all'}, default='all'
+        Type of feature impact to return:
+        - '**pos**' - Returns features with positive contribution.
+        - '**neg**' - Returns features with negative contribution.
+        - '**all**' - Returns all features with overall importance
+                  (absolute SHAP values).
+
+    Returns
+    -------
+    result : pandas.DataFrame
+        A sorted DataFrame containing feature importance:
+        - For 'all' → columns: ['Features', 'Overall_Impact']
+        - For 'pos' → columns: ['Features', 'Positive_Impact']
+        - For 'neg' → columns: ['Features', 'Negative_Impact']
+
+    shap_values : shap.Explanation
+        Raw SHAP explanation object containing per-sample contributions.
+
+    Notes
+    -----
+    - For multi-class models, SHAP values are averaged across classes.
+    - Feature importance is computed using mean absolute SHAP values.
+    - The function also stores SHAP values globally in `_shap_val`.
+
+    Raises
+    ------
+    ValueError
+        If `impact_type` is not one of {'pos', 'neg', 'all'}.
+
+    Example
+    -------
+    >>> result, shap_vals = explainer(model, X_test, impact_type='all')
+    >>> print(result.head())
+
+    """
+
+    ## All the Shap values with magnitude based as well!
+    features = [ ]
+    all_values = [ ]
+
+    neg_values = [ ]
+    neg_feature = [ ]
+
+    pos_values = [ ]
+    pos_feature = [ ]
+
+    explain = shap.TreeExplainer(model = model)
+    
+    shap_values = explain(X = data)
+
+    global _shap_val
+    _shap_val = shap_values 
+
+    vals = _shap_val.values
+
+    if vals.ndim >= 3 and impact_type == 'all':
+        vals = np.abs(vals).mean(axis = (0, 2))
+    elif vals.ndim == 2 and impact_type == 'all':
+        vals = np.abs(vals).mean(axis=0)
+
+    elif (impact_type == "pos" or impact_type == "neg") and vals.ndim >=3:
+        vals = vals.mean(axis=(0, 2))
+    elif (impact_type == "pos" or impact_type == "neg") and vals.ndim == 2:
+        vals = vals.mean(axis = 0)
+    
+    else:
+        raise ValueError("Invalid Impact type or dimentions of shap values")
+
+    for feature, value in zip(data.columns, vals):
+
+            features.append(feature)
+            all_values.append(value)
+
+            if value < 0:
+                neg_values.append(value)
+                neg_feature.append(feature)
+                
+            else:
+                pos_values.append(value)
+                pos_feature.append(feature)
+                
+    if impact_type == 'neg':
+            result = pd.DataFrame({
+                        "Features" : neg_feature,
+                        "Negative_Impact" : neg_values
+                    }).sort_values(by="Negative_Impact", ascending=False)  
+            
+    elif impact_type == 'pos':
+            result = pd.DataFrame({
+                "Features" : pos_feature,
+                "Positive_Impact" : pos_values
+
+            }).sort_values(by="Positive_Impact", ascending=False)  
+                
+    elif impact_type == 'all':
+            result = pd.DataFrame({
+                "Features" : features,
+                "Overall_Impact" : all_values
+            }).sort_values(by="Overall_Impact", ascending=False)        
+        
+    else:
+            raise ValueError("Invalid Impact type : must be neg, pos or all")
+        
+    return result, shap_values
+
+
+def summary_plot(data):
+    '''
+    Summary plot for feature contribution for all the classes.
+    '''
+    
+    shap.summary_plot(_shap_val, data)
+    
+
+def bar_plot(n_classes):
+        '''
+        Bar plot analysis of feature contribution for each class 
+        '''
+        for class_id in range(n_classes):    
+            plt.title(f"For class_id {class_id}")
+            shap.plots.bar(_shap_val[..., class_id])
+            plt.tight_layout()
+            plt.show()
+
+
+# def force_plot(shap_values):
+#       pass
+
+    
+def tree_plot(model , feature_names, size:tuple):
+    plt.figure(figsize=size)
+    tree.plot_tree(model, filled=True, feature_names=feature_names, class_names=True)
+    plt.tight_layout()
+    plt.show()
+
+
+
+
+
+
+
+
+
+    
+    
+
+
+
+            
+