Add code examples to Feature Selection Module API (#582)

datacubeR · datacubeR · solegalli · web-flow · commit bbd95e8c2551 · 2023-02-26T14:37:14.000+01:00
* Adding Examples for Feature Selection Module

* Fixing examples after review

* Update recursive_feature_elimination.py

* Update smart_correlation_selection.py

* Update shuffle_features.py

---------

Co-authored-by: datacubeR &lt;datacuber@pop-os.localdomain&gt;
Co-authored-by: Soledad Galli &lt;solegalli@protonmail.com&gt;
diff --git a/feature_engine/selection/drop_constant_features.py b/feature_engine/selection/drop_constant_features.py
@@ -101,6 +101,35 @@ class DropConstantFeatures(BaseSelector):
     See Also
     --------
     sklearn.feature_selection.VarianceThreshold
+
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from feature_engine.selection import DropConstantFeatures
+    >>> X = pd.DataFrame(dict(x1 = [1,1,1,1],
+    >>>                     x2 = ["a", "a", "b", "c"],
+    >>>                     x3 = [True, False, False, True]))
+    >>> dcf = DropConstantFeatures()
+    >>> dcf.fit_transform(X)
+        x2     x3
+    0  a   True
+    1  a  False
+    2  b  False
+    3  c   True
+
+    Additionally, you can set the Threshold for quasi-constant features:
+
+    >>> X = pd.DataFrame(dict(x1 = [1,1,1,1],
+    >>>                      x2 = ["a", "a", "b", "c"],
+    >>>                      x3 = [True, False, False, False]))
+    >>> dcf = DropConstantFeatures(tol = 0.75)
+    >>> dcf.fit_transform(X)
+        x2
+    0  a
+    1  a
+    2  b
+    3  c
     """
 
     def __init__(
diff --git a/feature_engine/selection/drop_correlated_features.py b/feature_engine/selection/drop_correlated_features.py
@@ -112,6 +112,20 @@ class DropCorrelatedFeatures(BaseSelector):
     --------
     pandas.corr
     feature_engine.selection.SmartCorrelationSelection
+
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from feature_engine.selection import DropCorrelatedFeatures
+    >>> X = pd.DataFrame(dict(x1 = [1,2,1,1], x2 = [2,4,3,1], x3 = [1, 0, 0, 1]))
+    >>> dcf = DropCorrelatedFeatures(threshold=0.7)
+    >>> dcf.fit_transform(X)
+        x1  x3
+    0   1   1
+    1   2   0
+    2   1   0
+    3   1   1
     """
 
     def __init__(
diff --git a/feature_engine/selection/drop_duplicate_features.py b/feature_engine/selection/drop_duplicate_features.py
@@ -90,6 +90,21 @@ class DropDuplicateFeatures(BaseSelector):
     transform:
         Remove duplicated features.
 
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from feature_engine.selection import DropDuplicateFeatures
+    >>> X = pd.DataFrame(dict(x1 = [1,1,1,1],
+    >>>                     x2 = [1,1,1,1],
+    >>>                     x3 = [True, False, False, False]))
+    >>> ddf = DropDuplicateFeatures()
+    >>> ddf.fit_transform(X)
+        x1     x3
+    0   1   True
+    1   1  False
+    2   1  False
+    3   1  False
     """
 
     def __init__(
diff --git a/feature_engine/selection/drop_features.py b/feature_engine/selection/drop_features.py
@@ -52,6 +52,22 @@ class DropFeatures(BaseSelector):
 
     transform:
         Drops indicated features.
+
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from feature_engine.selection import DropFeatures
+    >>> X = pd.DataFrame(dict(x1 = [1,2,3,4],
+    >>>                         x2 = ["a", "a", "b", "c"],
+    >>>                         x3 = [True, False, False, True]))
+    >>> df = DropFeatures(features_to_drop=["x2"])
+    >>> df.fit_transform(X)
+        x1     x3
+    0   1   True
+    1   2  False
+    2   3  False
+    3   4   True
     """
 
     def __init__(self, features_to_drop: List[Union[str, int]]):
diff --git a/feature_engine/selection/drop_psi_features.py b/feature_engine/selection/drop_psi_features.py
@@ -213,6 +213,28 @@ class DropHighPSIFeatures(BaseSelector):
     .. [1] Yurdakul B. "Statistical properties of population stability index".
        Western Michigan University, 2018.
        https://scholarworks.wmich.edu/dissertations/3208/
+
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from feature_engine.selection import DropHighPSIFeatures
+    >>> X = pd.DataFrame(dict(x1 = [1,1,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
+    >>>                 x2 = [32,87,6,32,11,44,8,7,9,0,32,87,6,32,11,44,8,7,9,0]))
+    >>> psi = DropHighPSIFeatures()
+    >>> psi.fit_transform(X)
+        x2
+    0   32
+    1   87
+    2    6
+    3   32
+    4   11
+    5   44
+    6    8
+    7    7
+    8    9
+    9    0
+    10  32
     """
 
     def __init__(
diff --git a/feature_engine/selection/information_value.py b/feature_engine/selection/information_value.py
@@ -141,6 +141,25 @@ class SelectByInformationValue(BaseSelector, WoE):
 
     .. [2] WoE and IV for continuous variables
         https://www.listendata.com/2019/08/WOE-IV-Continuous-Dependent.html
+
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from feature_engine.selection import SelectByInformationValue
+    >>> X = pd.DataFrame(dict(x1 = [1,1,1,1,1,1],
+    >>>                     x2 = [3,2,2,3,3,2],
+    >>>                     x3 = ["a","b","c","a","c","b"]))
+    >>> y = pd.Series([1,1,1,0,0,0])
+    >>> iv = SelectByInformationValue()
+    >>> iv.fit_transform(X, y)
+        x2
+    0   3
+    1   2
+    2   2
+    3   3
+    4   3
+    5   2
     """
 
     def __init__(
diff --git a/feature_engine/selection/recursive_feature_addition.py b/feature_engine/selection/recursive_feature_addition.py
@@ -112,6 +112,27 @@ class RecursiveFeatureAddition(BaseRecursiveSelector):
 
     {transform}
 
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>> from feature_engine.selection import RecursiveFeatureAddition
+    >>> X = pd.DataFrame(dict(x1 = [1000,2000,1000,1000,2000,3000],
+    >>>                     x2 = [2,4,3,1,2,2],
+    >>>                     x3 = [1,1,1,0,0,0],
+    >>>                     x4 = [1,2,1,1,0,1],
+    >>>                     x5 = [1,1,1,1,1,1]))
+    >>> y = pd.Series([1,0,0,1,1,0])
+    >>> rfa = RecursiveFeatureAddition(RandomForestClassifier(random_state=42), cv=2)
+    >>> rfa.fit_transform(X, y)
+       x2  x4
+    0   2   1
+    1   4   2
+    2   3   1
+    3   1   1
+    4   2   0
+    5   2   1
     """
 
     def fit(self, X: pd.DataFrame, y: pd.Series):
diff --git a/feature_engine/selection/recursive_feature_elimination.py b/feature_engine/selection/recursive_feature_elimination.py
@@ -112,6 +112,27 @@ class RecursiveFeatureElimination(BaseRecursiveSelector):
 
     {transform}
 
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>> from feature_engine.selection import RecursiveFeatureElimination
+    >>> X = pd.DataFrame(dict(x1 = [1000,2000,1000,1000,2000,3000],
+    >>>                     x2 = [2,4,3,1,2,2],
+    >>>                     x3 = [1,1,1,0,0,0],
+    >>>                     x4 = [1,2,1,1,0,1],
+    >>>                     x5 = [1,1,1,1,1,1]))
+    >>> y = pd.Series([1,0,0,1,1,0])
+    >>> rfe = RecursiveFeatureElimination(RandomForestClassifier(random_state=2), cv=2)
+    >>> rfe.fit_transform(X, y)
+       x2
+    0   2
+    1   4
+    2   3
+    3   1
+    4   2
+    5   2
     """
 
     def fit(self, X: pd.DataFrame, y: pd.Series):
diff --git a/feature_engine/selection/shuffle_features.py b/feature_engine/selection/shuffle_features.py
@@ -134,6 +134,32 @@ class SelectByShuffling(BaseSelector):
     See Also
     --------
     sklearn.inspection.permutation_importance
+
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>> from feature_engine.selection import SelectByShuffling
+    >>> X = pd.DataFrame(dict(x1 = [1000,2000,1000,1000,2000,3000],
+    >>>                     x2 = [2,4,3,1,2,2],
+    >>>                     x3 = [1,1,1,0,0,0],
+    >>>                     x4 = [1,2,1,1,0,1],
+    >>>                     x5 = [1,1,1,1,1,1]))
+    >>> y = pd.Series([1,0,0,1,1,0])
+    >>> sbs = SelectByShuffling(
+    >>>         RandomForestClassifier(random_state=42),
+    >>>         cv=2,
+    >>>         random_state=42,
+    >>>       )
+    >>> sbs.fit_transform(X, y)
+       x2  x4  x5
+    0   2   1   1
+    1   4   2   1
+    2   3   1   1
+    3   1   1   1
+    4   2   0   1
+    5   2   1   1
     """
 
     def __init__(
diff --git a/feature_engine/selection/single_feature_performance.py b/feature_engine/selection/single_feature_performance.py
@@ -115,6 +115,30 @@ class SelectBySingleFeaturePerformance(BaseSelector):
 
     .. [1] Galli S. "Machine Learning in Financial Risk Assessment".
         https://www.youtube.com/watch?v=KHGGlozsRtA
+
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>> from feature_engine.selection import SelectBySingleFeaturePerformance
+    >>> X = pd.DataFrame(dict(x1 = [1000,2000,1000,1000,2000,3000],
+    >>>                     x2 = [2,4,3,1,2,2],
+    >>>                     x3 = [1,1,1,0,0,0],
+    >>>                     x4 = [1,2,1,1,0,1],
+    >>>                     x5 = [1,1,1,1,1,1]))
+    >>> y = pd.Series([1,0,0,1,1,0])
+    >>> sfp = SelectBySingleFeaturePerformance(
+    >>>                     RandomForestClassifier(random_state=42),
+    >>>                     cv=2)
+    >>> sfp.fit_transform(X, y)
+        x2  x3
+    0   2   1
+    1   4   1
+    2   3   1
+    3   1   0
+    4   2   0
+    5   2   0
     """
 
     def __init__(
diff --git a/feature_engine/selection/smart_correlation_selection.py b/feature_engine/selection/smart_correlation_selection.py
@@ -152,6 +152,36 @@ class SmartCorrelatedSelection(BaseSelector):
     --------
     pandas.corr
     feature_engine.selection.DropCorrelatedFeatures
+
+    Examples
+    --------
+
+    >>> import pandas as pd
+    >>> from feature_engine.selection import SmartCorrelatedSelection
+    >>> X = pd.DataFrame(dict(x1 = [1,2,1,1],
+    >>>                 x2 = [2,4,3,1],
+    >>>                 x3 = [1, 0, 0, 0]))
+    >>> scs = SmartCorrelatedSelection(threshold=0.7)
+    >>> scs.fit_transform(X)
+       x2  x3
+    0   2   1
+    1   4   0
+    2   3   0
+    3   1   0
+
+    It is also possible alternative selection methods, in this case seleting
+    features with higher variance:
+
+    >>> X = pd.DataFrame(dict(x1 = [2,4,3,1],
+    >>>                 x2 = [1000,2000,1500,500],
+    >>>                 x3 = [1, 0, 0, 0]))
+    >>> scs = SmartCorrelatedSelection(threshold=0.7, selection_method="variance")
+    >>> scs.fit_transform(X)
+         x2  x3
+    0  1000   1
+    1  2000   0
+    2  1500   0
+    3   500   0
     """
 
     def __init__(
diff --git a/feature_engine/selection/target_mean_selection.py b/feature_engine/selection/target_mean_selection.py
@@ -167,6 +167,41 @@ class SelectByTargetMeanPerformance(BaseSelector):
     .. [1] Miller, et al. "Predicting customer behaviour: The University of Melbourne’s
         KDD Cup report". JMLR Workshop and Conference Proceeding. KDD 2009
         http://proceedings.mlr.press/v7/miller09/miller09.pdf
+
+    Examples
+    --------
+
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>> from feature_engine.selection import SelectByTargetMeanPerformance
+    >>> X = pd.DataFrame(dict(x1 = [1000,2000,1000,1000,2000,3000],
+    >>>                     x2 = [1,1,1,0,0,0],
+    >>>                     x3 = [1,2,1,1,0,1],
+    >>>                     x4 = [1,1,1,1,1,1]))
+    >>> y = pd.Series([1,0,0,1,1,0])
+    >>> tmp = SelectByTargetMeanPerformance(bins = 3, cv=2,scoring='accuracy')
+    >>> tmp.fit_transform(X, y)
+        x2  x3  x4
+    0   1   1   1
+    1   1   2   1
+    2   1   1   1
+    3   0   1   1
+    4   0   0   1
+    5   0   1   1
+
+    This transformer also works with Categorical examples:
+
+    >>> X = pd.DataFrame(dict(x1 = ["a","b","a","a","b","b"],
+    >>>             x2 = ["a","a","a","b","b","b"]))
+    >>> y = pd.Series([1,0,0,1,1,0])
+    >>> tmp = SelectByTargetMeanPerformance(bins = 3, cv=2,scoring='accuracy')
+    >>> tmp.fit_transform(X, y)
+      x2
+    0  a
+    1  a
+    2  a
+    3  b
+    4  b
+    5  b
     """
 
     def __init__(
