API Reference

class feature_engine.creation.CombineWithReferenceFeature(variables_to_combine, reference_variables, operations=['sub'], new_variables_names=None, missing_values='ignore')[source]

CombineWithReferenceFeature() applies basic mathematical operations between a group of variables and one or more reference features. It adds one or more additional features to the dataframe with the result of the operations.

In other words, CombineWithReferenceFeature() sums, multiplies, subtracts or divides a group of features to / by a group of reference variables, and returns the result as new variables in the dataframe.

For example, if we have the variables number_payments_first_quarter, number_payments_second_quarter, number_payments_third_quarter, number_payments_fourth_quarter, and total_payments, we can use CombineWithReferenceFeature() to determine the percentage of payments per quarter as follows:

transformer = CombineWithReferenceFeature(




Xt = transformer.fit_transform(X)

The transformed X, Xt, will contain the additional features indicated in the new_variables_name list plus the original set of variables.

variables_to_combine: list

The list of numerical variables to be combined with the reference variables.

reference_variables: list

The list of numerical reference variables that will be added to, multiplied with, or subtracted from the variables_to_combine, or used as denominator for division.

operations: list, default=[‘sub’]

The list of basic mathematical operations to be used in transformation.

If None, all of [‘sub’, ‘div’,’add’,’mul’] will be performed. Alternatively, you can enter a list of operations to carry out. Each operation should be a string and must be one of the elements in ['sub', 'div','add', 'mul'].

Each operation will result in a new variable that will be added to the transformed dataset.

new_variables_names: list, default=None

Names of the newly created variables. You can enter a list with the names for the newly created features (recommended). You must enter as many names as new features created by the transformer. The number of new features is the number of operations times the number of reference variables times the number of variables to combine.

Thus, if you want to perform 2 operations, sub and div, combining 4 variables with 2 reference variables, you should enter 2 X 4 X 2 new variable names.

The name of the variables indicated by the user should coincide with the order in which the operations are performed by the transformer. The transformer will first carry out ‘sub’, then ‘div’, then ‘add’ and finally ‘mul’.

If new_variable_names is None, the transformer will assign an arbitrary name to the newly created features.

missing_values: string, default=’ignore’

Indicates if missing values should be ignored or raised. If ‘ignore’, the transformer will ignore missing data when transforming the data. If ‘raise’ the transformer will return an error if the training or the datasets to transform contain missing values.



The number of features in the train set used in fit.


Although the transformer in essence allows us to combine any feature with any of the allowed mathematical operations, its used is intended mostly for the creation of new features based on some domain knowledge. Typical examples within the financial sector are:

  • Ratio between income and debt to create the debt_to_income_ratio.

  • Subtraction of rent from income to obtain the disposable_income.



This transformer does not learn parameters.


Combine the variables with the mathematical operations.


Fit to the data, then transform it.

fit(X, y=None)[source]

This transformer does not learn any parameter. Performs dataframe checks.

X: pandas dataframe of shape = [n_samples, n_features]

The training input samples. Can be the entire dataframe, not just the variables to transform.

y: pandas Series, or np.array. Default=None.

It is not needed in this transformer. You can pass y or None.

  • If the input is not a Pandas DataFrame

  • If any user provided variables are not numerical


If any of the reference variables contain null values and the mathematical operation is ‘div’.


Combine the variables with the mathematical operations.

X: pandas dataframe of shape = [n_samples, n_features]

The data to transform.

X: Pandas dataframe, shape = [n_samples, n_features + n_operations]

The dataframe with the operations results added as columns.


DataFrame ..


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.

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),

combinator = CombineWithReferenceFeature(
    operations = ['sub'],
    new_variables_names = ['LotPartial']
    ), y_train)
X_train_ = combinator.transform(X_train)

    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