OOFMeanEncoder for Feature-engine

An upstream snapshot, not a standalone project.

Everything in this repository except one file is feature-engine/feature_engine at v1.9.4, unmodified — the same feature_engine/, tests/ and docs/ tree. The one addition is feature_engine/encoding/oof_mean_encoding.py.

If you are looking for Feature-engine you want feature-engine/feature_engine, not this repository. This is a working snapshot of a change that is being proposed back to Feature-engine.

OOFMeanEncoder is a target (mean) encoder that learns its mapping out of fold, so that no row is encoded using its own target.

Upstream status

Item	State
Issue #1050 — add an out-of-fold target encoder	open, under discussion

The change is ready and tested here; it goes upstream as a pull request once the maintainers have weighed in on #1050.

The problem it solves

MeanEncoder replaces a category with the mean target observed for that category. Estimated and applied on the same rows, each row contributes to its own encoded value — 1/k of it, where k is the number of rows in its category. At k = 1 the encoding is the label: a model trained on it scores beautifully and predicts nothing.

category_encoders.TargetEncoder(cv=...) and CatBoost's ordered target statistics solve the same problem. This is not a new idea. What was missing is an implementation that follows the Feature-engine conventions: variables, missing_values, ignore_format, unseen, return_empty, smoothing, and DataFrames in and out.

Measured effect

demo_oof_mean_encoder.py, 300 categories with 3 rows each (900 training rows), the same model on the same rows:

Encoding	corr(encoded, target)	train AUC	validation AUC
MeanEncoder (in sample — leaks)	0.617	0.838	0.625
OOFMeanEncoder (out of fold)	0.093	0.551	0.625

Validation AUC is identical. The leaking encoder's 0.838 training score was never real signal — it is 0.213 AUC of optimism about itself. The out-of-fold training score is one you can act on.

What was added

File	Change
feature_engine/encoding/oof_mean_encoding.py	new — OOFMeanEncoder
feature_engine/encoding/__init__.py	exports OOFMeanEncoder
tests/test_encoding/test_oof_mean_encoder.py	new — 46 tests
docs/api_doc/encoding/OOFMeanEncoder.rst	new API page
docs/api_doc/encoding/index.rst	encoder table and toctree entry
demo_oof_mean_encoder.py	runnable demonstration
CONTRIBUTION.md	what was added, and what was not

tests/test_encoding passes in full — 389 tests, including the project's own test_check_estimator_encoders.py estimator-compliance suite.

Licence

Feature-engine is distributed under the BSD 3-Clause licence. This snapshot carries the same licence — see LICENSE.md, unchanged from upstream.

Where this is going

The same transformer is proposed to Feature-engine itself. Once it lands there, this snapshot should be archived in favour of the upstream repository.