def fit(self, X, y=None, **kwargs):
"""Fit encoder according to X and y.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vectors, where n_samples is the number of samples
and n_features is the number of features.
y : array-like, shape = [n_samples]
Target values.
Returns
-------
self : encoder
Returns self.
"""
# if the input dataset isn't already a dataframe, convert it to one (using default column names)
# first check the type
X = util.convert_input(X)
self._dim = X.shape[1]
# if columns aren't passed, just use every string column
if self.cols is None:
self.cols = util.get_obj_cols(X)
else:
self.cols = util.convert_cols_to_list(self.cols)
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
# train an ordinal pre-encoder
self.ordinal_encoder = OrdinalEncoder(verbose=self.verbose,
cols=self.cols,
handle_unknown='value',
handle_missing='value')
self.ordinal_encoder = self.ordinal_encoder.fit(X)
ordinal_mapping = self.ordinal_encoder.category_mapping
mappings_out = []
for switch in ordinal_mapping:
values = switch.get('mapping')
col = switch.get('col')
column_mapping = self.fit_polynomial_coding(
col, values, self.handle_missing, self.handle_unknown)
mappings_out.append({
'col': switch.get('col'),
'mapping': column_mapping,
})
self.mapping = mappings_out
X_temp = self.transform(X, override_return_df=True)
self.feature_names = X_temp.columns.tolist()
# drop all output columns with 0 variance.
if self.drop_invariant:
self.drop_cols = []
generated_cols = util.get_generated_cols(X, X_temp, self.cols)
self.drop_cols = [
x for x in generated_cols if X_temp[x].var() <= 10e-5
]
try:
[self.feature_names.remove(x) for x in self.drop_cols]
except KeyError as e:
if self.verbose > 0:
print("Could not remove column from feature names."
"Not found in generated cols.\n{}".format(e))
return self
class PolynomialEncoder(BaseEstimator, TransformerMixin):
"""Polynomial contrast coding for the encoding of categorical features.
Parameters
----------
verbose: int
integer indicating verbosity of the output. 0 for none.
cols: list
a list of columns to encode, if None, all string columns will be encoded.
drop_invariant: bool
boolean for whether or not to drop columns with 0 variance.
return_df: bool
boolean for whether to return a pandas DataFrame from transform (otherwise it will be a numpy array).
handle_unknown: str
options are 'error', 'return_nan', 'value', and 'indicator'. The default is 'value'. Warning: if indicator is used,
an extra column will be added in if the transform matrix has unknown categories. This can cause
unexpected changes in dimension in some cases.
handle_missing: str
options are 'error', 'return_nan', 'value', and 'indicator'. The default is 'value'. Warning: if indicator is used,
an extra column will be added in if the transform matrix has nan values. This can cause
unexpected changes in dimension in some cases.
Example
-------
>>> from category_encoders_sjw import *
>>> import pandas as pd
>>> from sklearn.datasets import load_boston
>>> bunch = load_boston()
>>> y = bunch.target
>>> X = pd.DataFrame(bunch.data, columns=bunch.feature_names)
>>> enc = PolynomialEncoder(cols=['CHAS', 'RAD']).fit(X, y)
>>> numeric_dataset = enc.transform(X)
>>> print(numeric_dataset.info())
<class 'pandas.core.frame.DataFrame'>
RangeIndex: 506 entries, 0 to 505
Data columns (total 21 columns):
intercept 506 non-null int64
CRIM 506 non-null float64
ZN 506 non-null float64
INDUS 506 non-null float64
CHAS_0 506 non-null float64
NOX 506 non-null float64
RM 506 non-null float64
AGE 506 non-null float64
DIS 506 non-null float64
RAD_0 506 non-null float64
RAD_1 506 non-null float64
RAD_2 506 non-null float64
RAD_3 506 non-null float64
RAD_4 506 non-null float64
RAD_5 506 non-null float64
RAD_6 506 non-null float64
RAD_7 506 non-null float64
TAX 506 non-null float64
PTRATIO 506 non-null float64
B 506 non-null float64
LSTAT 506 non-null float64
dtypes: float64(20), int64(1)
memory usage: 83.1 KB
None
References
----------
.. [1] Contrast Coding Systems for Categorical Variables, from
https://stats.idre.ucla.edu/r/library/r-library-contrast-coding-systems-for-categorical-variables/
.. [2] Gregory Carey (2003). Coding Categorical Variables, from
http://psych.colorado.edu/~carey/Courses/PSYC5741/handouts/Coding%20Categorical%20Variables%202006-03-03.pdf
"""
def __init__(self,
verbose=0,
cols=None,
mapping=None,
drop_invariant=False,
return_df=True,
handle_unknown='value',
handle_missing='value'):
self.return_df = return_df
self.drop_invariant = drop_invariant
self.drop_cols = []
self.verbose = verbose
self.mapping = mapping
self.handle_unknown = handle_unknown
self.handle_missing = handle_missing
self.cols = cols
self.ordinal_encoder = None
self._dim = None
self.feature_names = None
def fit(self, X, y=None, **kwargs):
"""Fit encoder according to X and y.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vectors, where n_samples is the number of samples
and n_features is the number of features.
y : array-like, shape = [n_samples]
Target values.
Returns
-------
self : encoder
Returns self.
"""
# if the input dataset isn't already a dataframe, convert it to one (using default column names)
# first check the type
X = util.convert_input(X)
self._dim = X.shape[1]
# if columns aren't passed, just use every string column
if self.cols is None:
self.cols = util.get_obj_cols(X)
else:
self.cols = util.convert_cols_to_list(self.cols)
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
# train an ordinal pre-encoder
self.ordinal_encoder = OrdinalEncoder(verbose=self.verbose,
cols=self.cols,
handle_unknown='value',
handle_missing='value')
self.ordinal_encoder = self.ordinal_encoder.fit(X)
ordinal_mapping = self.ordinal_encoder.category_mapping
mappings_out = []
for switch in ordinal_mapping:
values = switch.get('mapping')
col = switch.get('col')
column_mapping = self.fit_polynomial_coding(
col, values, self.handle_missing, self.handle_unknown)
mappings_out.append({
'col': switch.get('col'),
'mapping': column_mapping,
})
self.mapping = mappings_out
X_temp = self.transform(X, override_return_df=True)
self.feature_names = X_temp.columns.tolist()
# drop all output columns with 0 variance.
if self.drop_invariant:
self.drop_cols = []
generated_cols = util.get_generated_cols(X, X_temp, self.cols)
self.drop_cols = [
x for x in generated_cols if X_temp[x].var() <= 10e-5
]
try:
[self.feature_names.remove(x) for x in self.drop_cols]
except KeyError as e:
if self.verbose > 0:
print("Could not remove column from feature names."
"Not found in generated cols.\n{}".format(e))
return self
def transform(self, X, override_return_df=False):
"""Perform the transformation to new categorical data.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Returns
-------
p : array, shape = [n_samples, n_numeric + N]
Transformed values with encoding applied.
"""
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
if self._dim is None:
raise ValueError(
'Must train encoder before it can be used to transform data.')
# first check the type
X = util.convert_input(X)
# then make sure that it is the right size
if X.shape[1] != self._dim:
raise ValueError('Unexpected input dimension %d, expected %d' % (
X.shape[1],
self._dim,
))
if not self.cols:
return X
X = self.ordinal_encoder.transform(X)
if self.handle_unknown == 'error':
if X[self.cols].isin([-1]).any().any():
raise ValueError(
'Columns to be encoded can not contain new values')
X = self.polynomial_coding(X, self.mapping)
if self.drop_invariant:
for col in self.drop_cols:
X.drop(col, 1, inplace=True)
if self.return_df or override_return_df:
return X
else:
return X.values
@staticmethod
def fit_polynomial_coding(col, values, handle_missing, handle_unknown):
if handle_missing == 'value':
values = values[values > 0]
values_to_encode = values.values
if len(values) < 2:
return pd.DataFrame(index=values_to_encode)
if handle_unknown == 'indicator':
values_to_encode = np.append(values_to_encode, -1)
polynomial_contrast_matrix = Poly().code_without_intercept(
values_to_encode)
df = pd.DataFrame(
data=polynomial_contrast_matrix.matrix,
index=values_to_encode,
columns=[
str(col) + '_%d' % (i, )
for i in range(len(polynomial_contrast_matrix.column_suffixes))
])
if handle_unknown == 'return_nan':
df.loc[-1] = np.nan
elif handle_unknown == 'value':
df.loc[-1] = np.zeros(len(values_to_encode) - 1)
if handle_missing == 'return_nan':
df.loc[values.loc[np.nan]] = np.nan
elif handle_missing == 'value':
df.loc[-2] = np.zeros(len(values_to_encode) - 1)
return df
@staticmethod
def polynomial_coding(X_in, mapping):
"""
"""
X = X_in.copy(deep=True)
cols = X.columns.values.tolist()
X['intercept'] = pd.Series([1] * X.shape[0], index=X.index)
for switch in mapping:
col = switch.get('col')
mod = switch.get('mapping')
base_df = mod.reindex(X[col])
base_df.set_index(X.index, inplace=True)
X = pd.concat([base_df, X], axis=1)
old_column_index = cols.index(col)
cols[old_column_index:old_column_index + 1] = mod.columns
cols = ['intercept'] + cols
return X.reindex(columns=cols)
def get_feature_names(self):
"""
Returns the names of all transformed / added columns.
Returns
-------
feature_names: list
A list with all feature names transformed or added.
Note: potentially dropped features are not included!
"""
if not isinstance(self.feature_names, list):
raise ValueError(
"Estimator has to be fitted to return feature names.")
else:
return self.feature_names
def fit(self, X, y, **kwargs):
"""Fit encoder according to X and binary y.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vectors, where n_samples is the number of samples
and n_features is the number of features.
y : array-like, shape = [n_samples]
Binary target values.
Returns
-------
self : encoder
Returns self.
"""
# Unite parameters into pandas types
X = util.convert_input(X)
y = util.convert_input_vector(y, X.index).astype(float)
# The lengths must be equal
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) + ".")
self._dim = X.shape[1]
# If columns aren't passed, just use every string column
if self.cols is None:
self.cols = util.get_obj_cols(X)
else:
self.cols = util.convert_cols_to_list(self.cols)
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
self.ordinal_encoder = OrdinalEncoder(verbose=self.verbose,
cols=self.cols,
handle_unknown='value',
handle_missing='value')
self.ordinal_encoder = self.ordinal_encoder.fit(X)
X_ordinal = self.ordinal_encoder.transform(X)
# Training
if self.model == 'independent':
self.mapping = self._train_independent(X_ordinal, y)
elif self.model == 'pooled':
self.mapping = self._train_pooled(X_ordinal, y)
elif self.model == 'beta':
self.mapping = self._train_beta(X_ordinal, y)
elif self.model == 'binary':
# The label must be binary with values {0,1}
unique = y.unique()
if len(unique) != 2:
raise ValueError(
"The target column y must be binary. But the target contains "
+ str(len(unique)) + " unique value(s).")
if y.isnull().any():
raise ValueError(
"The target column y must not contain missing values.")
if np.max(unique) < 1:
raise ValueError(
"The target column y must be binary with values {0, 1}. Value 1 was not found in the target."
)
if np.min(unique) > 0:
raise ValueError(
"The target column y must be binary with values {0, 1}. Value 0 was not found in the target."
)
# Perform the training
self.mapping = self._train_log_odds_ratio(X_ordinal, y)
else:
raise ValueError("model='" + str(self.model) +
"' is not a recognized option")
X_temp = self.transform(X, override_return_df=True)
self.feature_names = X_temp.columns.tolist()
# Store column names with approximately constant variance on the training data
if self.drop_invariant:
self.drop_cols = []
generated_cols = util.get_generated_cols(X, X_temp, self.cols)
self.drop_cols = [
x for x in generated_cols if X_temp[x].var() <= 10e-5
]
try:
[self.feature_names.remove(x) for x in self.drop_cols]
except KeyError as e:
if self.verbose > 0:
print("Could not remove column from feature names."
"Not found in generated cols.\n{}".format(e))
return self
class BaseNEncoder(BaseEstimator, TransformerMixin):
"""Base-N encoder encodes the categories into arrays of their base-N representation. A base of 1 is equivalent to
one-hot encoding (not really base-1, but useful), a base of 2 is equivalent to binary encoding. N=number of actual
categories is equivalent to vanilla ordinal encoding.
Parameters
----------
verbose: int
integer indicating verbosity of the output. 0 for none.
cols: list
a list of columns to encode, if None, all string columns will be encoded.
drop_invariant: bool
boolean for whether or not to drop columns with 0 variance.
return_df: bool
boolean for whether to return a pandas DataFrame from transform (otherwise it will be a numpy array).
base: int
when the downstream model copes well with nonlinearities (like decision tree), use higher base.
handle_unknown: str
options are 'error', 'return_nan', 'value', and 'indicator'. The default is 'value'. Warning: if indicator is used,
an extra column will be added in if the transform matrix has unknown categories. This can cause
unexpected changes in dimension in some cases.
handle_missing: str
options are 'error', 'return_nan', 'value', and 'indicator'. The default is 'value'. Warning: if indicator is used,
an extra column will be added in if the transform matrix has nan values. This can cause
unexpected changes in dimension in some cases.
Example
-------
>>> from category_encoders_sjw import *
>>> import pandas as pd
>>> from sklearn.datasets import load_boston
>>> bunch = load_boston()
>>> y = bunch.target
>>> X = pd.DataFrame(bunch.data, columns=bunch.feature_names)
>>> enc = BaseNEncoder(cols=['CHAS', 'RAD']).fit(X, y)
>>> numeric_dataset = enc.transform(X)
>>> print(numeric_dataset.info())
<class 'pandas.core.frame.DataFrame'>
RangeIndex: 506 entries, 0 to 505
Data columns (total 18 columns):
CRIM 506 non-null float64
ZN 506 non-null float64
INDUS 506 non-null float64
CHAS_0 506 non-null int64
CHAS_1 506 non-null int64
NOX 506 non-null float64
RM 506 non-null float64
AGE 506 non-null float64
DIS 506 non-null float64
RAD_0 506 non-null int64
RAD_1 506 non-null int64
RAD_2 506 non-null int64
RAD_3 506 non-null int64
RAD_4 506 non-null int64
TAX 506 non-null float64
PTRATIO 506 non-null float64
B 506 non-null float64
LSTAT 506 non-null float64
dtypes: float64(11), int64(7)
memory usage: 71.3 KB
None
"""
def __init__(self, verbose=0, cols=None, mapping=None, drop_invariant=False, return_df=True, base=2,
handle_unknown='value', handle_missing='value'):
self.return_df = return_df
self.drop_invariant = drop_invariant
self.drop_cols = []
self.verbose = verbose
self.handle_unknown = handle_unknown
self.handle_missing = handle_missing
self.cols = cols
self.mapping = mapping
self.ordinal_encoder = None
self._dim = None
self.base = base
self._encoded_columns = None
self.feature_names = None
def fit(self, X, y=None, **kwargs):
"""Fit encoder according to X and y.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vectors, where n_samples is the number of samples
and n_features is the number of features.
y : array-like, shape = [n_samples]
Target values.
Returns
-------
self : encoder
Returns self.
"""
# if the input dataset isn't already a dataframe, convert it to one (using default column names)
X = util.convert_input(X)
self._dim = X.shape[1]
# if columns aren't passed, just use every string column
if self.cols is None:
self.cols = util.get_obj_cols(X)
else:
self.cols = util.convert_cols_to_list(self.cols)
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
# train an ordinal pre-encoder
self.ordinal_encoder = OrdinalEncoder(
verbose=self.verbose,
cols=self.cols,
handle_unknown='value',
handle_missing='value'
)
self.ordinal_encoder = self.ordinal_encoder.fit(X)
self.mapping = self.fit_base_n_encoding(X)
# do a transform on the training data to get a column list
X_temp = self.transform(X, override_return_df=True)
self._encoded_columns = X_temp.columns.values
self.feature_names = list(X_temp.columns)
# drop all output columns with 0 variance.
if self.drop_invariant:
self.drop_cols = []
generated_cols = util.get_generated_cols(X, X_temp, self.cols)
self.drop_cols = [x for x in generated_cols if X_temp[x].var() <= 10e-5]
try:
[self.feature_names.remove(x) for x in self.drop_cols]
except KeyError as e:
if self.verbose > 0:
print("Could not remove column from feature names."
"Not found in generated cols.\n{}".format(e))
return self
def fit_base_n_encoding(self, X):
mappings_out = []
for switch in self.ordinal_encoder.category_mapping:
col = switch.get('col')
values = switch.get('mapping')
if self.handle_missing == 'value':
values = values[values > 0]
if self.handle_unknown == 'indicator':
values = np.append(values, -1)
digits = self.calc_required_digits(values)
X_unique = pd.DataFrame(index=values,
columns=[str(col) + '_%d' % x for x in range(digits)],
data=np.array([self.col_transform(x, digits) for x in range(1, len(values) + 1)]))
if self.handle_unknown == 'return_nan':
X_unique.loc[-1] = np.nan
elif self.handle_unknown == 'value':
X_unique.loc[-1] = 0
if self.handle_missing == 'return_nan':
X_unique.loc[values.loc[np.nan]] = np.nan
elif self.handle_missing == 'value':
X_unique.loc[-2] = 0
mappings_out.append({'col': col, 'mapping': X_unique})
return mappings_out
def transform(self, X, override_return_df=False):
"""Perform the transformation to new categorical data.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Returns
-------
p : array, shape = [n_samples, n_numeric + N]
Transformed values with encoding applied.
"""
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
if self._dim is None:
raise ValueError('Must train encoder before it can be used to transform data.')
# first check the type
X = util.convert_input(X)
# then make sure that it is the right size
if X.shape[1] != self._dim:
raise ValueError('Unexpected input dimension %d, expected %d' % (X.shape[1], self._dim,))
if not self.cols:
return X
X_out = self.ordinal_encoder.transform(X)
if self.handle_unknown == 'error':
if X_out[self.cols].isin([-1]).any().any():
raise ValueError('Columns to be encoded can not contain new values')
X_out = self.basen_encode(X_out, cols=self.cols)
if self.drop_invariant:
for col in self.drop_cols:
X_out.drop(col, 1, inplace=True)
# impute missing values only in the generated columns
# generated_cols = util.get_generated_cols(X, X_out, self.cols)
# X_out[generated_cols] = X_out[generated_cols].fillna(value=0.0)
if self.return_df or override_return_df:
return X_out
else:
return X_out.values
def inverse_transform(self, X_in):
"""
Perform the inverse transformation to encoded data.
Parameters
----------
X_in : array-like, shape = [n_samples, n_features]
Returns
-------
p: array, the same size of X_in
"""
# fail fast
if self._dim is None:
raise ValueError('Must train encoder before it can be used to inverse_transform data')
# unite the type into pandas dataframe (it makes the input size detection code easier...) and make deep copy
X = util.convert_input(X_in, columns=self.feature_names, deep=True)
X = self.basen_to_integer(X, self.cols, self.base)
# make sure that it is the right size
if X.shape[1] != self._dim:
if self.drop_invariant:
raise ValueError("Unexpected input dimension %d, the attribute drop_invariant should "
"be False when transforming the data" % (X.shape[1],))
else:
raise ValueError('Unexpected input dimension %d, expected %d' % (X.shape[1], self._dim,))
if not self.cols:
return X if self.return_df else X.values
for switch in self.ordinal_encoder.mapping:
column_mapping = switch.get('mapping')
inverse = pd.Series(data=column_mapping.index, index=column_mapping.values)
X[switch.get('col')] = X[switch.get('col')].map(inverse).astype(switch.get('data_type'))
if self.handle_unknown == 'return_nan' and self.handle_missing == 'return_nan':
for col in self.cols:
if X[switch.get('col')].isnull().any():
warnings.warn("inverse_transform is not supported because transform impute "
"the unknown category nan when encode %s" % (col,))
return X if self.return_df else X.values
def calc_required_digits(self, values):
# figure out how many digits we need to represent the classes present
if self.base == 1:
digits = len(values) + 1
else:
digits = int(np.ceil(math.log(len(values), self.base))) + 1
return digits
def basen_encode(self, X_in, cols=None):
"""
Basen encoding encodes the integers as basen code with one column per digit.
Parameters
----------
X_in: DataFrame
cols: list-like, default None
Column names in the DataFrame to be encoded
Returns
-------
dummies : DataFrame
"""
X = X_in.copy(deep=True)
cols = X.columns.values.tolist()
for switch in self.mapping:
col = switch.get('col')
mod = switch.get('mapping')
base_df = mod.reindex(X[col])
base_df.set_index(X.index, inplace=True)
X = pd.concat([base_df, X], axis=1)
old_column_index = cols.index(col)
cols[old_column_index: old_column_index + 1] = mod.columns
return X.reindex(columns=cols)
def basen_to_integer(self, X, cols, base):
"""
Convert basen code as integers.
Parameters
----------
X : DataFrame
encoded data
cols : list-like
Column names in the DataFrame that be encoded
base : int
The base of transform
Returns
-------
numerical: DataFrame
"""
out_cols = X.columns.values.tolist()
for col in cols:
col_list = [col0 for col0 in out_cols if re.match(str(col)+'_\\d+', str(col0))]
insert_at = out_cols.index(col_list[0])
if base == 1:
value_array = np.array([int(col0.split('_')[-1]) for col0 in col_list])
else:
len0 = len(col_list)
value_array = np.array([base ** (len0 - 1 - i) for i in range(len0)])
X.insert(insert_at, col, np.dot(X[col_list].values, value_array.T))
X.drop(col_list, axis=1, inplace=True)
out_cols = X.columns.values.tolist()
return X
def col_transform(self, col, digits):
"""
The lambda body to transform the column values
"""
if col is None or float(col) < 0.0:
return None
else:
col = self.number_to_base(int(col), self.base, digits)
if len(col) == digits:
return col
else:
return [0 for _ in range(digits - len(col))] + col
@staticmethod
def number_to_base(n, b, limit):
if b == 1:
return [0 if n != _ else 1 for _ in range(limit)]
if n == 0:
return [0 for _ in range(limit)]
digits = []
for _ in range(limit):
digits.append(int(n % b))
n, _ = divmod(n, b)
return digits[::-1]
def get_feature_names(self):
"""
Returns the names of all transformed / added columns.
Returns
-------
feature_names: list
A list with all feature names transformed or added.
Note: potentially dropped features are not included!
"""
if not isinstance(self.feature_names, list):
raise ValueError('Must fit data first. Affected feature names are not known before.')
else:
return self.feature_names
class JamesSteinEncoder(BaseEstimator, TransformerMixin):
"""James-Stein estimator.
For feature value `i`, James-Stein estimator returns a weighted average of:
1. The mean target value for the observed feature value `i`.
2. The mean target value (regardless of the feature value).
This can be written as::
JS_i = (1-B)*mean(y_i) + B*mean(y)
The question is, what should be the weight `B`?
If we put too much weight on the conditional mean value, we will overfit.
If we put too much weight on the global mean, we will underfit.
The canonical solution in machine learning is to perform cross-validation.
However, Charles Stein came with a closed-form solution to the problem.
The intuition is: If the estimate of `mean(y_i)` is unreliable (`y_i` has high variance),
we should put more weight on `mean(y)`. Stein put it into an equation as::
B = var(y_i) / (var(y_i)+var(y))
The only remaining issue is that we do not know `var(y)`, let alone `var(y_i)`.
Hence, we have to estimate the variances. But how can we reliably estimate the
variances, when we already struggle with the estimation of the mean values?!
There are multiple solutions:
1. If we have the same count of observations for each feature value `i` and all
`y_i` are close to each other, we can pretend that all `var(y_i)` are identical.
This is called a pooled model.
2. If the observation counts are not equal, it makes sense to replace the variances
with squared standard errors, which penalize small observation counts::
SE^2 = var(y)/count(y)
This is called an independent model.
James-Stein estimator has, however, one practical limitation - it was defined
only for normal distributions. If you want to apply it for binary classification,
which allows only values {0, 1}, it is better to first convert the mean target value
from the bound interval <0,1> into an unbounded interval by replacing mean(y)
with log-odds ratio::
log-odds_ratio_i = log(mean(y_i)/mean(y_not_i))
This is called binary model. The estimation of parameters of this model is, however,
tricky and sometimes it fails fatally. In these situations, it is better to use beta
model, which generally delivers slightly worse accuracy than binary model but does
not suffer from fatal failures.
Parameters
----------
verbose: int
integer indicating verbosity of the output. 0 for none.
cols: list
a list of columns to encode, if None, all string columns will be encoded.
drop_invariant: bool
boolean for whether or not to drop encoded columns with 0 variance.
return_df: bool
boolean for whether to return a pandas DataFrame from transform (otherwise it will be a numpy array).
handle_missing: str
options are 'return_nan', 'error' and 'value', defaults to 'value', which returns the prior probability.
handle_unknown: str
options are 'return_nan', 'error' and 'value', defaults to 'value', which returns the prior probability.
model: str
options are 'pooled', 'beta', 'binary' and 'independent', defaults to 'independent'.
randomized: bool,
adds normal (Gaussian) distribution noise into training data in order to decrease overfitting (testing data are untouched).
sigma: float
standard deviation (spread or "width") of the normal distribution.
Example
-------
>>> from category_encoders_sjw import *
>>> import pandas as pd
>>> from sklearn.datasets import load_boston
>>> bunch = load_boston()
>>> y = bunch.target
>>> X = pd.DataFrame(bunch.data, columns=bunch.feature_names)
>>> enc = JamesSteinEncoder(cols=['CHAS', 'RAD']).fit(X, y)
>>> numeric_dataset = enc.transform(X)
>>> print(numeric_dataset.info())
<class 'pandas.core.frame.DataFrame'>
RangeIndex: 506 entries, 0 to 505
Data columns (total 13 columns):
CRIM 506 non-null float64
ZN 506 non-null float64
INDUS 506 non-null float64
CHAS 506 non-null float64
NOX 506 non-null float64
RM 506 non-null float64
AGE 506 non-null float64
DIS 506 non-null float64
RAD 506 non-null float64
TAX 506 non-null float64
PTRATIO 506 non-null float64
B 506 non-null float64
LSTAT 506 non-null float64
dtypes: float64(13)
memory usage: 51.5 KB
None
References
----------
.. [1] Parametric empirical Bayes inference: Theory and applications, equations 1.19 & 1.20, from
https://www.jstor.org/stable/2287098
.. [2] Empirical Bayes for multiple sample sizes, from
http://chris-said.io/2017/05/03/empirical-bayes-for-multiple-sample-sizes/
.. [3] Shrinkage Estimation of Log-odds Ratios for Comparing Mobility Tables, from
https://journals.sagepub.com/doi/abs/10.1177/0081175015570097
.. [4] Stein's paradox and group rationality, from
http://www.philos.rug.nl/~romeyn/presentation/2017_romeijn_-_Paris_Stein.pdf
.. [5] Stein's Paradox in Statistics, from
http://statweb.stanford.edu/~ckirby/brad/other/Article1977.pdf
"""
def __init__(self,
verbose=0,
cols=None,
drop_invariant=False,
return_df=True,
handle_unknown='value',
handle_missing='value',
model='independent',
random_state=None,
randomized=False,
sigma=0.05):
self.verbose = verbose
self.return_df = return_df
self.drop_invariant = drop_invariant
self.drop_cols = []
self.cols = cols
self.ordinal_encoder = None
self._dim = None
self.mapping = None
self.handle_unknown = handle_unknown
self.handle_missing = handle_missing
self.random_state = random_state
self.randomized = randomized
self.sigma = sigma
self.model = model
self.feature_names = None
# noinspection PyUnusedLocal
def fit(self, X, y, **kwargs):
"""Fit encoder according to X and binary y.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vectors, where n_samples is the number of samples
and n_features is the number of features.
y : array-like, shape = [n_samples]
Binary target values.
Returns
-------
self : encoder
Returns self.
"""
# Unite parameters into pandas types
X = util.convert_input(X)
y = util.convert_input_vector(y, X.index).astype(float)
# The lengths must be equal
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) + ".")
self._dim = X.shape[1]
# If columns aren't passed, just use every string column
if self.cols is None:
self.cols = util.get_obj_cols(X)
else:
self.cols = util.convert_cols_to_list(self.cols)
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
self.ordinal_encoder = OrdinalEncoder(verbose=self.verbose,
cols=self.cols,
handle_unknown='value',
handle_missing='value')
self.ordinal_encoder = self.ordinal_encoder.fit(X)
X_ordinal = self.ordinal_encoder.transform(X)
# Training
if self.model == 'independent':
self.mapping = self._train_independent(X_ordinal, y)
elif self.model == 'pooled':
self.mapping = self._train_pooled(X_ordinal, y)
elif self.model == 'beta':
self.mapping = self._train_beta(X_ordinal, y)
elif self.model == 'binary':
# The label must be binary with values {0,1}
unique = y.unique()
if len(unique) != 2:
raise ValueError(
"The target column y must be binary. But the target contains "
+ str(len(unique)) + " unique value(s).")
if y.isnull().any():
raise ValueError(
"The target column y must not contain missing values.")
if np.max(unique) < 1:
raise ValueError(
"The target column y must be binary with values {0, 1}. Value 1 was not found in the target."
)
if np.min(unique) > 0:
raise ValueError(
"The target column y must be binary with values {0, 1}. Value 0 was not found in the target."
)
# Perform the training
self.mapping = self._train_log_odds_ratio(X_ordinal, y)
else:
raise ValueError("model='" + str(self.model) +
"' is not a recognized option")
X_temp = self.transform(X, override_return_df=True)
self.feature_names = X_temp.columns.tolist()
# Store column names with approximately constant variance on the training data
if self.drop_invariant:
self.drop_cols = []
generated_cols = util.get_generated_cols(X, X_temp, self.cols)
self.drop_cols = [
x for x in generated_cols if X_temp[x].var() <= 10e-5
]
try:
[self.feature_names.remove(x) for x in self.drop_cols]
except KeyError as e:
if self.verbose > 0:
print("Could not remove column from feature names."
"Not found in generated cols.\n{}".format(e))
return self
def transform(self, X, y=None, override_return_df=False):
"""Perform the transformation to new categorical data. When the data are used for model training,
it is important to also pass the target in order to apply leave one out.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
y : array-like, shape = [n_samples] when transform by leave one out
None, when transform without target information (such as transform test set)
Returns
-------
p : array, shape = [n_samples, n_numeric + N]
Transformed values with encoding applied.
"""
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
if self._dim is None:
raise ValueError(
'Must train encoder before it can be used to transform data.')
# Unite the input into pandas types
X = util.convert_input(X)
# Then make sure that it is the right size
if X.shape[1] != self._dim:
raise ValueError('Unexpected input dimension %d, expected %d' % (
X.shape[1],
self._dim,
))
# If we are encoding the training data, we have to check the target
if y is not None:
y = util.convert_input_vector(y, X.index).astype(float)
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) +
".")
if not self.cols:
return X
# Do not modify the input argument
X = X.copy(deep=True)
X = self.ordinal_encoder.transform(X)
if self.handle_unknown == 'error':
if X[self.cols].isin([-1]).any().any():
raise ValueError('Unexpected categories found in dataframe')
# Loop over columns and replace nominal values with WOE
X = self._score(X, y)
# Postprocessing
# Note: We should not even convert these columns.
if self.drop_invariant:
for col in self.drop_cols:
X.drop(col, 1, inplace=True)
if self.return_df or override_return_df:
return X
else:
return X.values
def fit_transform(self, X, y=None, **fit_params):
"""
Encoders that utilize the target must make sure that the training data are transformed with:
transform(X, y)
and not with:
transform(X)
"""
# the interface requires 'y=None' in the signature but we need 'y'
if y is None:
raise (TypeError, 'fit_transform() missing argument: ' 'y' '')
return self.fit(X, y, **fit_params).transform(X, y)
def _train_pooled(self, X, y):
# Implemented based on reference [1]
# Initialize the output
mapping = {}
# Calculate global statistics
prior = y.mean()
target_var = y.var()
global_count = len(y)
for switch in self.ordinal_encoder.category_mapping:
col = switch.get('col')
values = switch.get('mapping')
# Calculate sum and count of the target for each unique value in the feature col
stats = y.groupby(X[col]).agg(['mean', 'count'])
# See: Computer Age Statistical Inference: Algorithms, Evidence, and Data Science (Bradley Efron & Trevor Hastie, 2016)
# Equations 7.19 and 7.20.
# Note: The equations assume normal distribution of the label. But our label is p(y|x),
# which is definitely not normally distributed as probabilities are bound to lie on interval 0..1.
# We make this approximation because Efron does it as well.
# Equation 7.19
# Explanation of the equation:
# https://stats.stackexchange.com/questions/191444/variance-in-estimating-p-for-a-binomial-distribution
# if stats['count'].var() > 0:
# warnings.warn('The pooled model assumes that each category is observed exactly N times. This was violated in "' + str(col) +'" column. Consider comparing the accuracy of this model to "independent" model.')
# This is a parametric estimate of var(p) in the binomial distribution.
# We do not use it because we also want to support non-binary targets.
# The difference in the estimates is small.
# variance = prior * (1 - prior) / stats['count'].mean()
# This is a squared estimate of standard error of the mean:
# https://en.wikipedia.org/wiki/Standard_error
variance = target_var / (stats['count'].mean())
# Equation 7.20
SSE = ((stats['mean'] - prior)**2).sum() # Sum of Squared Errors
if SSE > 0: # We have to avoid division by zero
B = ((len(stats['count']) - 3) * variance) / SSE
B = B.clip(0, 1)
estimate = prior + (1 - B) * (stats['mean'] - prior)
else:
estimate = stats['mean']
# Ignore unique values. This helps to prevent overfitting on id-like columns
# This works better than: estimate[stats['count'] == 1] = prior
if len(stats['mean']) == global_count:
estimate[:] = prior
if self.handle_unknown == 'return_nan':
estimate.loc[-1] = np.nan
elif self.handle_unknown == 'value':
estimate.loc[-1] = prior
if self.handle_missing == 'return_nan':
estimate.loc[values.loc[np.nan]] = np.nan
elif self.handle_missing == 'value':
estimate.loc[-2] = prior
# Store the estimate for transform() function
mapping[col] = estimate
return mapping
def _train_independent(self, X, y):
# Implemented based on reference [2]
# Initialize the output
mapping = {}
# Calculate global statistics
prior = y.mean()
global_count = len(y)
global_var = y.var()
for switch in self.ordinal_encoder.category_mapping:
col = switch.get('col')
values = switch.get('mapping')
# Calculate sum and count of the target for each unique value in the feature col
stats = y.groupby(X[col]).agg(['mean', 'var'])
i_var = stats['var'].fillna(
0) # When we do not have more than 1 sample, assume 0 variance
unique_cnt = len(X[col].unique())
# See: Parametric Empirical Bayes Inference: Theory and Applications (Morris, 1983)
# Equations 1.19 and 1.20.
# Note: The equations assume normal distribution of the label. But our label is p(y|x),
# which is definitely not normally distributed as probabilities are bound to lie on interval 0..1.
# Nevertheless, it seems to perform surprisingly well. This is in agreement with:
# Data Analysis with Stein's Estimator and Its Generalizations (Efron & Morris, 1975)
# The equations are similar to James-Stein estimator, as listed in:
# Stein's Paradox in Statistics (Efron & Morris, 1977)
# Or:
# Computer Age Statistical Inference: Algorithms, Evidence, and Data Science (Efron & Hastie, 2016)
# Equations 7.19 and 7.20.
# The difference is that they have equal count of observations per estimated variable, while we generally
# do not have that. Nice discussion about that is given at:
# http://chris-said.io/2017/05/03/empirical-bayes-for-multiple-sample-sizes/
smoothing = i_var / (global_var + i_var) * (unique_cnt -
3) / (unique_cnt - 1)
smoothing = 1 - smoothing
smoothing = smoothing.clip(
lower=0, upper=1) # Smoothing should be in the interval <0,1>
estimate = smoothing * (stats['mean']) + (1 - smoothing) * prior
# Ignore unique values. This helps to prevent overfitting on id-like columns
if len(stats['mean']) == global_count:
estimate[:] = prior
if self.handle_unknown == 'return_nan':
estimate.loc[-1] = np.nan
elif self.handle_unknown == 'value':
estimate.loc[-1] = prior
if self.handle_missing == 'return_nan':
estimate.loc[values.loc[np.nan]] = np.nan
elif self.handle_missing == 'value':
estimate.loc[-2] = prior
# Store the estimate for transform() function
mapping[col] = estimate
return mapping
def _train_log_odds_ratio(self, X, y):
# Implemented based on reference [3]
# Initialize the output
mapping = {}
# Calculate global statistics
global_sum = y.sum()
global_count = y.count()
# Iterative estimation of mu and sigma as given on page 9.
# This problem is traditionally solved with Newton-Raphson method:
# https://en.wikipedia.org/wiki/Newton%27s_method
# But we just use sklearn minimizer.
def get_best_sigma(sigma, mu_k, sigma_k, K):
global mu # Ugly. But I want to be able to read it once the optimization ends.
w_k = 1. / (sigma**2 + sigma_k**2) # Weights depends on sigma
mu = sum(w_k * mu_k) / sum(w_k) # Mu transitively depends on sigma
total = sum(w_k *
(mu_k - mu)**2) # We want this to be close to K-1
loss = abs(total - (K - 1))
return loss
for switch in self.ordinal_encoder.category_mapping:
col = switch.get('col')
values = switch.get('mapping')
# Calculate sum and count of the target for each unique value in the feature col
stats = y.groupby(X[col]).agg(['sum', 'count'
]) # Count of x_{i,+} and x_i
# Create 2x2 contingency table
crosstable = pd.DataFrame()
crosstable['E-A-'] = global_count - stats['count'] + stats[
'sum'] - global_sum
crosstable['E-A+'] = stats['count'] - stats['sum']
crosstable['E+A-'] = global_sum - stats['sum']
crosstable['E+A+'] = stats['sum']
index = crosstable.index.values
crosstable = np.array(
crosstable,
dtype=np.float32) # The argument unites the types into float
# Count of contingency tables.
K = len(crosstable)
# Ignore id-like columns. This helps to prevent overfitting.
if K == global_count:
estimate = pd.Series(0, index=values)
else:
if K > 1: # We want to avoid division by zero in y_k calculation
# Estimate log-odds ratios with Yates correction as listed on page 5.
mu_k = np.log(
(crosstable[:, 0] + 0.5) * (crosstable[:, 3] + 0.5) /
((crosstable[:, 1] + 0.5) * (crosstable[:, 2] + 0.5)))
# Standard deviation estimate for 2x2 contingency table as given in equation 2.
# The explanation of the equation is given in:
# https://stats.stackexchange.com/questions/266098/how-do-i-calculate-the-standard-deviation-of-the-log-odds
sigma_k = np.sqrt(np.sum(1. / (crosstable + 0.5), axis=1))
# Estimate the sigma and mu. Sigma is non-negative.
result = scipy.optimize.minimize(get_best_sigma,
x0=1e-4,
args=(mu_k, sigma_k, K),
bounds=[(0, np.inf)],
method='TNC',
tol=1e-12,
options={
'gtol': 1e-12,
'ftol': 1e-12,
'eps': 1e-12
})
sigma = result.x[0]
# Empirical Bayes follows equation 7.
# However, James-Stein estimator behaves perversely when K < 3. Hence, we clip the B into interval <0,1>.
# Literature reference for the clipping:
# Estimates of Income for Small Places: An Application of James-Stein Procedures to Census Data (Fay & Harriout, 1979),
# page 270.
B = (K - 3) * sigma_k**2 / ((K - 1) *
(sigma**2 + sigma_k**2))
B = B.clip(0, 1)
y_k = mu + (1 - B) * (mu_k - mu)
# Convert Numpy vector back into Series
estimate = pd.Series(y_k, index=index)
else:
estimate = pd.Series(0, index=values)
if self.handle_unknown == 'return_nan':
estimate.loc[-1] = np.nan
elif self.handle_unknown == 'value':
estimate.loc[-1] = 0
if self.handle_missing == 'return_nan':
estimate.loc[values.loc[np.nan]] = np.nan
elif self.handle_missing == 'value':
estimate.loc[-2] = 0
# Store the estimate for transform() function
mapping[col] = estimate
return mapping
def _train_beta(self, X, y):
# Implemented based on reference [4]
# Initialize the output
mapping = {}
# Calculate global statistics
prior = y.mean()
global_count = len(y)
for switch in self.ordinal_encoder.category_mapping:
col = switch.get('col')
values = switch.get('mapping')
# Calculate sum and count of the target for each unique value in the feature col
stats = y.groupby(X[col]).agg(['mean', 'count'])
# See: Stein's paradox and group rationality (Romeijn, 2017), page 14
smoothing = stats['count'] / (stats['count'] + global_count)
estimate = smoothing * (stats['mean']) + (1 - smoothing) * prior
# Ignore unique values. This helps to prevent overfitting on id-like columns
if len(stats['mean']) == global_count:
estimate[:] = prior
if self.handle_unknown == 'return_nan':
estimate.loc[-1] = np.nan
elif self.handle_unknown == 'value':
estimate.loc[-1] = prior
if self.handle_missing == 'return_nan':
estimate.loc[values.loc[np.nan]] = np.nan
elif self.handle_missing == 'value':
estimate.loc[-2] = prior
# Store the estimate for transform() function
mapping[col] = estimate
return mapping
def _score(self, X, y):
for col in self.cols:
# Score the column
X[col] = X[col].map(self.mapping[col])
# Randomization is meaningful only for training data -> we do it only if y is present
if self.randomized and y is not None:
random_state_generator = check_random_state(self.random_state)
X[col] = (X[col] * random_state_generator.normal(
1., self.sigma, X[col].shape[0]))
return X
def get_feature_names(self):
"""
Returns the names of all transformed / added columns.
Returns
-------
feature_names: list
A list with all feature names transformed or added.
Note: potentially dropped features are not included!
"""
if not isinstance(self.feature_names, list):
raise ValueError(
"Estimator has to be fitted to return feature names.")
else:
return self.feature_names
def fit(self, X, y, **kwargs):
"""Fit encoder according to X and y.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vectors, where n_samples is the number of samples
and n_features is the number of features.
y : array-like, shape = [n_samples]
Target values.
Returns
-------
self : encoder
Returns self.
"""
# unite the input into pandas types
X = util.convert_input(X)
y = util.convert_input_vector(y, X.index)
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) + ".")
self._dim = X.shape[1]
# if columns aren't passed, just use every string column
if self.cols is None:
self.cols = util.get_obj_cols(X)
else:
self.cols = util.convert_cols_to_list(self.cols)
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
self.ordinal_encoder = OrdinalEncoder(verbose=self.verbose,
cols=self.cols,
handle_unknown='value',
handle_missing='value')
self.ordinal_encoder = self.ordinal_encoder.fit(X)
X_ordinal = self.ordinal_encoder.transform(X)
self.mapping = self.fit_target_encoding(X_ordinal, y)
X_temp = self.transform(X, override_return_df=True)
self.feature_names = list(X_temp.columns)
if self.drop_invariant:
self.drop_cols = []
X_temp = self.transform(X)
generated_cols = util.get_generated_cols(X, X_temp, self.cols)
self.drop_cols = [
x for x in generated_cols if X_temp[x].var() <= 10e-5
]
try:
[self.feature_names.remove(x) for x in self.drop_cols]
except KeyError as e:
if self.verbose > 0:
print("Could not remove column from feature names."
"Not found in generated cols.\n{}".format(e))
return self
class TargetEncoder(BaseEstimator, TransformerMixin):
"""Target encoding for categorical features.
For the case of categorical target: features are replaced with a blend of posterior probability of the target
given particular categorical value and the prior probability of the target over all the training data.
For the case of continuous target: features are replaced with a blend of the expected value of the target
given particular categorical value and the expected value of the target over all the training data.
Parameters
----------
verbose: int
integer indicating verbosity of the output. 0 for none.
cols: list
a list of columns to encode, if None, all string columns will be encoded.
drop_invariant: bool
boolean for whether or not to drop columns with 0 variance.
return_df: bool
boolean for whether to return a pandas DataFrame from transform (otherwise it will be a numpy array).
handle_missing: str
options are 'error', 'return_nan' and 'value', defaults to 'value', which returns the target mean.
handle_unknown: str
options are 'error', 'return_nan' and 'value', defaults to 'value', which returns the target mean.
min_samples_leaf: int
minimum samples to take category average into account.
smoothing: float
smoothing effect to balance categorical average vs prior. Higher value means stronger regularization.
The value must be strictly bigger than 0.
Example
-------
>>> from category_encoders_sjw import *
>>> import pandas as pd
>>> from sklearn.datasets import load_boston
>>> bunch = load_boston()
>>> y = bunch.target
>>> X = pd.DataFrame(bunch.data, columns=bunch.feature_names)
>>> enc = TargetEncoder(cols=['CHAS', 'RAD']).fit(X, y)
>>> numeric_dataset = enc.transform(X)
>>> print(numeric_dataset.info())
<class 'pandas.core.frame.DataFrame'>
RangeIndex: 506 entries, 0 to 505
Data columns (total 13 columns):
CRIM 506 non-null float64
ZN 506 non-null float64
INDUS 506 non-null float64
CHAS 506 non-null float64
NOX 506 non-null float64
RM 506 non-null float64
AGE 506 non-null float64
DIS 506 non-null float64
RAD 506 non-null float64
TAX 506 non-null float64
PTRATIO 506 non-null float64
B 506 non-null float64
LSTAT 506 non-null float64
dtypes: float64(13)
memory usage: 51.5 KB
None
References
----------
.. [1] A Preprocessing Scheme for High-Cardinality Categorical Attributes in Classification and Prediction Problems, from
https://dl.acm.org/citation.cfm?id=507538
"""
def __init__(self,
verbose=0,
cols=None,
drop_invariant=False,
return_df=True,
handle_missing='value',
handle_unknown='value',
min_samples_leaf=1,
smoothing=1.0):
self.return_df = return_df
self.drop_invariant = drop_invariant
self.drop_cols = []
self.verbose = verbose
self.cols = cols
self.ordinal_encoder = None
self.min_samples_leaf = min_samples_leaf
self.smoothing = float(
smoothing
) # Make smoothing a float so that python 2 does not treat as integer division
self._dim = None
self.mapping = None
self.handle_unknown = handle_unknown
self.handle_missing = handle_missing
self._mean = None
self.feature_names = None
def fit(self, X, y, **kwargs):
"""Fit encoder according to X and y.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vectors, where n_samples is the number of samples
and n_features is the number of features.
y : array-like, shape = [n_samples]
Target values.
Returns
-------
self : encoder
Returns self.
"""
# unite the input into pandas types
X = util.convert_input(X)
y = util.convert_input_vector(y, X.index)
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) + ".")
self._dim = X.shape[1]
# if columns aren't passed, just use every string column
if self.cols is None:
self.cols = util.get_obj_cols(X)
else:
self.cols = util.convert_cols_to_list(self.cols)
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
self.ordinal_encoder = OrdinalEncoder(verbose=self.verbose,
cols=self.cols,
handle_unknown='value',
handle_missing='value')
self.ordinal_encoder = self.ordinal_encoder.fit(X)
X_ordinal = self.ordinal_encoder.transform(X)
self.mapping = self.fit_target_encoding(X_ordinal, y)
X_temp = self.transform(X, override_return_df=True)
self.feature_names = list(X_temp.columns)
if self.drop_invariant:
self.drop_cols = []
X_temp = self.transform(X)
generated_cols = util.get_generated_cols(X, X_temp, self.cols)
self.drop_cols = [
x for x in generated_cols if X_temp[x].var() <= 10e-5
]
try:
[self.feature_names.remove(x) for x in self.drop_cols]
except KeyError as e:
if self.verbose > 0:
print("Could not remove column from feature names."
"Not found in generated cols.\n{}".format(e))
return self
def fit_target_encoding(self, X, y):
mapping = {}
for switch in self.ordinal_encoder.category_mapping:
col = switch.get('col')
values = switch.get('mapping')
prior = self._mean = y.mean()
stats = y.groupby(X[col]).agg(['count', 'mean'])
smoove = 1 / (1 + np.exp(
-(stats['count'] - self.min_samples_leaf) / self.smoothing))
smoothing = prior * (1 - smoove) + stats['mean'] * smoove
smoothing[stats['count'] == 1] = prior
if self.handle_unknown == 'return_nan':
smoothing.loc[-1] = np.nan
elif self.handle_unknown == 'value':
smoothing.loc[-1] = prior
if self.handle_missing == 'return_nan':
smoothing.loc[values.loc[np.nan]] = np.nan
elif self.handle_missing == 'value':
smoothing.loc[-2] = prior
mapping[col] = smoothing
return mapping
def transform(self, X, y=None, override_return_df=False):
"""Perform the transformation to new categorical data.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
y : array-like, shape = [n_samples] when transform by leave one out
None, when transform without target info (such as transform test set)
Returns
-------
p : array, shape = [n_samples, n_numeric + N]
Transformed values with encoding applied.
"""
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
if self._dim is None:
raise ValueError(
'Must train encoder before it can be used to transform data.')
# unite the input into pandas types
X = util.convert_input(X)
# then make sure that it is the right size
if X.shape[1] != self._dim:
raise ValueError('Unexpected input dimension %d, expected %d' % (
X.shape[1],
self._dim,
))
# if we are encoding the training data, we have to check the target
if y is not None:
y = util.convert_input_vector(y, X.index)
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) +
".")
if not self.cols:
return X
X = self.ordinal_encoder.transform(X)
if self.handle_unknown == 'error':
if X[self.cols].isin([-1]).any().any():
raise ValueError('Unexpected categories found in dataframe')
X = self.target_encode(X)
if self.drop_invariant:
for col in self.drop_cols:
X.drop(col, 1, inplace=True)
if self.return_df or override_return_df:
return X
else:
return X.values
def fit_transform(self, X, y=None, **fit_params):
"""
Encoders that utilize the target must make sure that the training data are transformed with:
transform(X, y)
and not with:
transform(X)
"""
# the interface requires 'y=None' in the signature but we need 'y'
if y is None:
raise (TypeError, 'fit_transform() missing argument: ' 'y' '')
return self.fit(X, y, **fit_params).transform(X, y)
def target_encode(self, X_in):
X = X_in.copy(deep=True)
for col in self.cols:
X[col] = X[col].map(self.mapping[col])
return X
def get_feature_names(self):
"""
Returns the names of all transformed / added columns.
Returns
-------
feature_names: list
A list with all feature names transformed or added.
Note: potentially dropped features are not included!
"""
if not isinstance(self.feature_names, list):
raise ValueError(
'Must fit data first. Affected feature names are not known before.'
)
else:
return self.feature_names
class WOEEncoder(BaseEstimator, TransformerMixin):
"""Weight of Evidence coding for categorical features.
Parameters
----------
verbose: int
integer indicating verbosity of the output. 0 for none.
cols: list
a list of columns to encode, if None, all string columns will be encoded.
drop_invariant: bool
boolean for whether or not to drop columns with 0 variance.
return_df: bool
boolean for whether to return a pandas DataFrame from transform (otherwise it will be a numpy array).
handle_missing: str
options are 'return_nan', 'error' and 'value', defaults to 'value', which will assume WOE=0.
handle_unknown: str
options are 'return_nan', 'error' and 'value', defaults to 'value', which will assume WOE=0.
randomized: bool,
adds normal (Gaussian) distribution noise into training data in order to decrease overfitting (testing data are untouched).
sigma: float
standard deviation (spread or "width") of the normal distribution.
regularization: float
the purpose of regularization is mostly to prevent division by zero.
When regularization is 0, you may encounter division by zero.
Example
-------
>>> from category_encoders_sjw import *
>>> import pandas as pd
>>> from sklearn.datasets import load_boston
>>> bunch = load_boston()
>>> y = bunch.target > 22.5
>>> X = pd.DataFrame(bunch.data, columns=bunch.feature_names)
>>> enc = WOEEncoder(cols=['CHAS', 'RAD']).fit(X, y)
>>> numeric_dataset = enc.transform(X)
>>> print(numeric_dataset.info())
<class 'pandas.core.frame.DataFrame'>
RangeIndex: 506 entries, 0 to 505
Data columns (total 13 columns):
CRIM 506 non-null float64
ZN 506 non-null float64
INDUS 506 non-null float64
CHAS 506 non-null float64
NOX 506 non-null float64
RM 506 non-null float64
AGE 506 non-null float64
DIS 506 non-null float64
RAD 506 non-null float64
TAX 506 non-null float64
PTRATIO 506 non-null float64
B 506 non-null float64
LSTAT 506 non-null float64
dtypes: float64(13)
memory usage: 51.5 KB
None
References
----------
.. [1] Weight of Evidence (WOE) and Information Value Explained, from
https://www.listendata.com/2015/03/weight-of-evidence-woe-and-information.html
"""
def __init__(self,
verbose=0,
cols=None,
drop_invariant=False,
return_df=True,
handle_unknown='value',
handle_missing='value',
random_state=None,
randomized=False,
sigma=0.05,
regularization=1.0):
self.verbose = verbose
self.return_df = return_df
self.drop_invariant = drop_invariant
self.drop_cols = []
self.cols = cols
self.ordinal_encoder = None
self._dim = None
self.mapping = None
self.handle_unknown = handle_unknown
self.handle_missing = handle_missing
self._sum = None
self._count = None
self.random_state = random_state
self.randomized = randomized
self.sigma = sigma
self.regularization = regularization
self.feature_names = None
# noinspection PyUnusedLocal
def fit(self, X, y, **kwargs):
"""Fit encoder according to X and binary y.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vectors, where n_samples is the number of samples
and n_features is the number of features.
y : array-like, shape = [n_samples]
Binary target values.
Returns
-------
self : encoder
Returns self.
"""
# Unite parameters into pandas types
X = util.convert_input(X)
y = util.convert_input_vector(y, X.index).astype(float)
# The lengths must be equal
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) + ".")
# The label must be binary with values {0,1}
unique = y.unique()
if len(unique) != 2:
raise ValueError(
"The target column y must be binary. But the target contains "
+ str(len(unique)) + " unique value(s).")
if y.isnull().any():
raise ValueError(
"The target column y must not contain missing values.")
if np.max(unique) < 1:
raise ValueError(
"The target column y must be binary with values {0, 1}. Value 1 was not found in the target."
)
if np.min(unique) > 0:
raise ValueError(
"The target column y must be binary with values {0, 1}. Value 0 was not found in the target."
)
self._dim = X.shape[1]
# If columns aren't passed, just use every string column
if self.cols is None:
self.cols = util.get_obj_cols(X)
else:
self.cols = util.convert_cols_to_list(self.cols)
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
self.ordinal_encoder = OrdinalEncoder(verbose=self.verbose,
cols=self.cols,
handle_unknown='value',
handle_missing='value')
self.ordinal_encoder = self.ordinal_encoder.fit(X)
X_ordinal = self.ordinal_encoder.transform(X)
# Training
self.mapping = self._train(X_ordinal, y)
X_temp = self.transform(X, override_return_df=True)
self.feature_names = X_temp.columns.tolist()
# Store column names with approximately constant variance on the training data
if self.drop_invariant:
self.drop_cols = []
generated_cols = util.get_generated_cols(X, X_temp, self.cols)
self.drop_cols = [
x for x in generated_cols if X_temp[x].var() <= 10e-5
]
try:
[self.feature_names.remove(x) for x in self.drop_cols]
except KeyError as e:
if self.verbose > 0:
print("Could not remove column from feature names."
"Not found in generated cols.\n{}".format(e))
return self
def transform(self, X, y=None, override_return_df=False):
"""Perform the transformation to new categorical data. When the data are used for model training,
it is important to also pass the target in order to apply leave one out.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
y : array-like, shape = [n_samples] when transform by leave one out
None, when transform without target information (such as transform test set)
Returns
-------
p : array, shape = [n_samples, n_numeric + N]
Transformed values with encoding applied.
"""
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
if self._dim is None:
raise ValueError(
'Must train encoder before it can be used to transform data.')
# Unite the input into pandas types
X = util.convert_input(X)
# Then make sure that it is the right size
if X.shape[1] != self._dim:
raise ValueError('Unexpected input dimension %d, expected %d' % (
X.shape[1],
self._dim,
))
# If we are encoding the training data, we have to check the target
if y is not None:
y = util.convert_input_vector(y, X.index).astype(float)
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) +
".")
if not self.cols:
return X
# Do not modify the input argument
X = X.copy(deep=True)
X = self.ordinal_encoder.transform(X)
if self.handle_unknown == 'error':
if X[self.cols].isin([-1]).any().any():
raise ValueError('Unexpected categories found in dataframe')
# Loop over columns and replace nominal values with WOE
X = self._score(X, y)
# Postprocessing
# Note: We should not even convert these columns.
if self.drop_invariant:
for col in self.drop_cols:
X.drop(col, 1, inplace=True)
if self.return_df or override_return_df:
return X
else:
return X.values
def fit_transform(self, X, y=None, **fit_params):
"""
Encoders that utilize the target must make sure that the training data are transformed with:
transform(X, y)
and not with:
transform(X)
"""
# the interface requires 'y=None' in the signature but we need 'y'
if y is None:
raise (TypeError, 'fit_transform() missing argument: ' 'y' '')
return self.fit(X, y, **fit_params).transform(X, y)
def _train(self, X, y):
# Initialize the output
mapping = {}
# Calculate global statistics
self._sum = y.sum()
self._count = y.count()
for switch in self.ordinal_encoder.category_mapping:
col = switch.get('col')
values = switch.get('mapping')
# Calculate sum and count of the target for each unique value in the feature col
stats = y.groupby(X[col]).agg(['sum', 'count'
]) # Count of x_{i,+} and x_i
# Create a new column with regularized WOE.
# Regularization helps to avoid division by zero.
# Pre-calculate WOEs because logarithms are slow.
nominator = (stats['sum'] + self.regularization) / (
self._sum + 2 * self.regularization)
denominator = ((stats['count'] - stats['sum']) +
self.regularization) / (self._count - self._sum +
2 * self.regularization)
woe = np.log(nominator / denominator)
# Ignore unique values. This helps to prevent overfitting on id-like columns.
woe[stats['count'] == 1] = 0
if self.handle_unknown == 'return_nan':
woe.loc[-1] = np.nan
elif self.handle_unknown == 'value':
woe.loc[-1] = 0
if self.handle_missing == 'return_nan':
woe.loc[values.loc[np.nan]] = np.nan
elif self.handle_missing == 'value':
woe.loc[-2] = 0
# Store WOE for transform() function
mapping[col] = woe
return mapping
def _score(self, X, y):
for col in self.cols:
# Score the column
X[col] = X[col].map(self.mapping[col])
# Randomization is meaningful only for training data -> we do it only if y is present
if self.randomized and y is not None:
random_state_generator = check_random_state(self.random_state)
X[col] = (X[col] * random_state_generator.normal(
1., self.sigma, X[col].shape[0]))
return X
def get_feature_names(self):
"""
Returns the names of all transformed / added columns.
Returns
-------
feature_names: list
A list with all feature names transformed or added.
Note: potentially dropped features are not included!
"""
if not isinstance(self.feature_names, list):
raise ValueError(
"Estimator has to be fitted to return feature names.")
else:
return self.feature_names
class MEstimateEncoder(BaseEstimator, TransformerMixin):
"""M-probability estimate of likelihood.
This is a simplified version of target encoder, which goes under names like m-probability estimate or
additive smoothing with known incidence rates. In comparison to target encoder, m-probability estimate
has only one tunable parameter (`m`), while target encoder has two tunable parameters (`min_samples_leaf`
and `smoothing`).
Parameters
----------
verbose: int
integer indicating verbosity of the output. 0 for none.
cols: list
a list of columns to encode, if None, all string columns will be encoded.
drop_invariant: bool
boolean for whether or not to drop encoded columns with 0 variance.
return_df: bool
boolean for whether to return a pandas DataFrame from transform (otherwise it will be a numpy array).
handle_missing: str
options are 'return_nan', 'error' and 'value', defaults to 'value', which returns the prior probability.
handle_unknown: str
options are 'return_nan', 'error' and 'value', defaults to 'value', which returns the prior probability.
randomized: bool,
adds normal (Gaussian) distribution noise into training data in order to decrease overfitting (testing data are untouched).
sigma: float
standard deviation (spread or "width") of the normal distribution.
m: float
this is the "m" in the m-probability estimate. Higher value of m results into stronger shrinking.
M is non-negative.
Example
-------
>>> from category_encoders_sjw import *
>>> import pandas as pd
>>> from sklearn.datasets import load_boston
>>> bunch = load_boston()
>>> y = bunch.target > 22.5
>>> X = pd.DataFrame(bunch.data, columns=bunch.feature_names)
>>> enc = MEstimateEncoder(cols=['CHAS', 'RAD']).fit(X, y)
>>> numeric_dataset = enc.transform(X)
>>> print(numeric_dataset.info())
<class 'pandas.core.frame.DataFrame'>
RangeIndex: 506 entries, 0 to 505
Data columns (total 13 columns):
CRIM 506 non-null float64
ZN 506 non-null float64
INDUS 506 non-null float64
CHAS 506 non-null float64
NOX 506 non-null float64
RM 506 non-null float64
AGE 506 non-null float64
DIS 506 non-null float64
RAD 506 non-null float64
TAX 506 non-null float64
PTRATIO 506 non-null float64
B 506 non-null float64
LSTAT 506 non-null float64
dtypes: float64(13)
memory usage: 51.5 KB
None
References
----------
.. [1] A Preprocessing Scheme for High-Cardinality Categorical Attributes in Classification and Prediction Problems, equation 7, from
https://dl.acm.org/citation.cfm?id=507538
.. [2] On estimating probabilities in tree pruning, equation 1, from
https://link.springer.com/chapter/10.1007/BFb0017010
.. [3] Additive smoothing, from
https://en.wikipedia.org/wiki/Additive_smoothing#Generalized_to_the_case_of_known_incidence_rates
"""
def __init__(self,
verbose=0,
cols=None,
drop_invariant=False,
return_df=True,
handle_unknown='value',
handle_missing='value',
random_state=None,
randomized=False,
sigma=0.05,
m=1.0):
self.verbose = verbose
self.return_df = return_df
self.drop_invariant = drop_invariant
self.drop_cols = []
self.cols = cols
self.ordinal_encoder = None
self._dim = None
self.mapping = None
self.handle_unknown = handle_unknown
self.handle_missing = handle_missing
self._sum = None
self._count = None
self.random_state = random_state
self.randomized = randomized
self.sigma = sigma
self.m = m
self.feature_names = None
# noinspection PyUnusedLocal
def fit(self, X, y, **kwargs):
"""Fit encoder according to X and binary y.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vectors, where n_samples is the number of samples
and n_features is the number of features.
y : array-like, shape = [n_samples]
Binary target values.
Returns
-------
self : encoder
Returns self.
"""
# Unite parameters into pandas types
X = util.convert_input(X)
y = util.convert_input_vector(y, X.index).astype(float)
# The lengths must be equal
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) + ".")
self._dim = X.shape[1]
# If columns aren't passed, just use every string column
if self.cols is None:
self.cols = util.get_obj_cols(X)
else:
self.cols = util.convert_cols_to_list(self.cols)
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
self.ordinal_encoder = OrdinalEncoder(verbose=self.verbose,
cols=self.cols,
handle_unknown='value',
handle_missing='value')
self.ordinal_encoder = self.ordinal_encoder.fit(X)
X_ordinal = self.ordinal_encoder.transform(X)
# Training
self.mapping = self._train(X_ordinal, y)
X_temp = self.transform(X, override_return_df=True)
self.feature_names = X_temp.columns.tolist()
# Store column names with approximately constant variance on the training data
if self.drop_invariant:
self.drop_cols = []
generated_cols = util.get_generated_cols(X, X_temp, self.cols)
self.drop_cols = [
x for x in generated_cols if X_temp[x].var() <= 10e-5
]
try:
[self.feature_names.remove(x) for x in self.drop_cols]
except KeyError as e:
if self.verbose > 0:
print("Could not remove column from feature names."
"Not found in generated cols.\n{}".format(e))
return self
def transform(self, X, y=None, override_return_df=False):
"""Perform the transformation to new categorical data.
When the data are used for model training, it is important to also pass the target in order to apply leave one out.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
y : array-like, shape = [n_samples] when transform by leave one out
None, when transform without target information (such as transform test set)
Returns
-------
p : array, shape = [n_samples, n_numeric + N]
Transformed values with encoding applied.
"""
if self.handle_missing == 'error':
if X[self.cols].isnull().any().any():
raise ValueError('Columns to be encoded can not contain null')
if self._dim is None:
raise ValueError(
'Must train encoder before it can be used to transform data.')
# Unite the input into pandas types
X = util.convert_input(X)
# Then make sure that it is the right size
if X.shape[1] != self._dim:
raise ValueError('Unexpected input dimension %d, expected %d' % (
X.shape[1],
self._dim,
))
# If we are encoding the training data, we have to check the target
if y is not None:
y = util.convert_input_vector(y, X.index).astype(float)
if X.shape[0] != y.shape[0]:
raise ValueError("The length of X is " + str(X.shape[0]) +
" but length of y is " + str(y.shape[0]) +
".")
if not self.cols:
return X
# Do not modify the input argument
X = X.copy(deep=True)
X = self.ordinal_encoder.transform(X)
if self.handle_unknown == 'error':
if X[self.cols].isin([-1]).any().any():
raise ValueError('Unexpected categories found in dataframe')
# Loop over the columns and replace the nominal values with the numbers
X = self._score(X, y)
# Postprocessing
# Note: We should not even convert these columns.
if self.drop_invariant:
for col in self.drop_cols:
X.drop(col, 1, inplace=True)
if self.return_df or override_return_df:
return X
else:
return X.values
def fit_transform(self, X, y=None, **fit_params):
"""
Encoders that utilize the target must make sure that the training data are transformed with:
transform(X, y)
and not with:
transform(X)
"""
# the interface requires 'y=None' in the signature but we need 'y'
if y is None:
raise (TypeError, 'fit_transform() missing argument: ' 'y' '')
return self.fit(X, y, **fit_params).transform(X, y)
def _train(self, X, y):
# Initialize the output
mapping = {}
# Calculate global statistics
self._sum = y.sum()
self._count = y.count()
prior = self._sum / self._count
for switch in self.ordinal_encoder.category_mapping:
col = switch.get('col')
values = switch.get('mapping')
# Calculate sum and count of the target for each unique value in the feature col
stats = y.groupby(X[col]).agg(['sum', 'count'
]) # Count of x_{i,+} and x_i
# Calculate the m-probability estimate
estimate = (stats['sum'] + prior * self.m) / (stats['count'] +
self.m)
# Ignore unique columns. This helps to prevent overfitting on id-like columns
if len(stats['count']) == self._count:
estimate[:] = prior
if self.handle_unknown == 'return_nan':
estimate.loc[-1] = np.nan
elif self.handle_unknown == 'value':
estimate.loc[-1] = prior
if self.handle_missing == 'return_nan':
estimate.loc[values.loc[np.nan]] = np.nan
elif self.handle_missing == 'value':
estimate.loc[-2] = prior
# Store the m-probability estimate for transform() function
mapping[col] = estimate
return mapping
def _score(self, X, y):
for col in self.cols:
# Score the column
X[col] = X[col].map(self.mapping[col])
# Randomization is meaningful only for training data -> we do it only if y is present
if self.randomized and y is not None:
random_state_generator = check_random_state(self.random_state)
X[col] = (X[col] * random_state_generator.normal(
1., self.sigma, X[col].shape[0]))
return X
def get_feature_names(self):
"""
Returns the names of all transformed / added columns.
Returns
-------
feature_names: list
A list with all feature names transformed or added.
Note: potentially dropped features are not included!
"""
if not isinstance(self.feature_names, list):
raise ValueError(
"Estimator has to be fitted to return feature names.")
else:
return self.feature_names
