add transformer to combine features with reference variable (#226)

* Initial commit issue #68 - Class Sketch

* Issue #68 initial commit

* Issue #68 - Docstring, unit tests Draft and other yerbas.

* #68 - code refactor and unit tests

* #68 - formatting and MyPy errors fixes

* #68 MyPy errors on tests directory fixes

* #68 - Circle CI error fixes

* fix grammar, rename new variable

* expands docstrings

* fix line lenght and indentation

* remove whitespace

* fixes whitespaces in docstrings

* edits jupyter notebook

* remove checks and fix typos

* change wording in docs

Co-authored-by: NicoGalli <[email protected]>

Author: solegalli

README.md

@@ -90,6 +90,7 @@ More resources will be added as they appear online!
 
 ### Variable Combinations:
  * MathematicalCombination
+ * CombineWithReferenceFeature
 
 ### Feature Selection:
  * DropFeatures

docs/creation/CombineWithReferenceFeature.rst

@@ -0,0 +1,55 @@
+CombineWithReferenceFeature
+===========================
+
+API Reference
+-------------
+
+.. autoclass:: feature_engine.creation.CombineWithReferenceFeature
+    :members:
+
+
+Example
+-------
+
+CombineWithReferenceFeature() combines a group of variables with a group of reference
+variables utilizing basic mathematical operations (subtraction, division, addition and
+multiplication), returning one or more additional features in the dataframe as a result.
+
+In this example, we subtract 2 variables from the house prices dataset.
+
+.. code:: python
+
+    import pandas as pd
+    from sklearn.model_selection import train_test_split
+
+    from feature_engine.creation import CombineWithReferenceFeature
+
+    data = pd.read_csv('houseprice.csv').fillna(0)
+
+    X_train, X_test, y_train, y_test = train_test_split(
+    data.drop(['Id', 'SalePrice'], axis=1),
+    data['SalePrice'],
+    test_size=0.3,
+    random_state=0
+    )
+
+    combinator = CombineWithReferenceFeature(
+        variables_to_combine=['LotArea'],
+        reference_variables=['LotFrontage'],
+        operations = ['sub'],
+        new_variables_names = ['LotPartial']
+        )
+
+    combinator.fit(X_train, y_train)
+    X_train_ = combinator.transform(X_train)
+
+    print(X_train_[["LotPartial","LotFrontage","LotArea"]].head())
+
+.. code:: python
+
+        LotTotal  LotFrontage  LotArea
+    64      9375.0          0.0     9375
+    682     2887.0          0.0     2887
+    960     7157.0         50.0     7207
+    1384    9000.0         60.0     9060
+    1100    8340.0         60.0     8400

docs/creation/index.rst

@@ -9,4 +9,5 @@ various mathematical and other methods.
 .. toctree::
    :maxdepth: 2
 
-   MathematicalCombination
+   MathematicalCombination
+   CombineWithReferenceFeature

docs/index.rst

@@ -149,6 +149,7 @@ Mathematical Combination:
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -  :doc:`creation/MathematicalCombination`: creates new variables by combining features with mathematical operations
+-  :doc:`creation/CombineWithReferenceFeature`: creates variables with reference features through mathematical operations
 
 Feature Selection:
 ~~~~~~~~~~~~~~~~~~