Skip to content
Tutorials Center
My learning

Topics

Lesson 60 of 111 ยท Feature Engineering and Pipelines

Custom Transformers and Estimators

Write your own scikit-learn transformer and classifier with BaseEstimator and the mixins: the fit/transform contract, get_params rules and contract tests.

Sooner or later a recipe will not fit any built-in class: clip outliers at learned percentiles, add domain-specific ratios, or try a classifier of your own design. You could write a loose function, but then it cannot live in a pipeline, it will not be cloned, and cross-validation will not refit it per fold. If your code follows the scikit-learn contract, all of that works for free, including grid search over its parameters.

The contract is small. This lesson shows how to write a transformer that learns something in fit, how to write a classifier, what the base classes give you, the rules that trip people up (__init__ and get_params), and how to test that your class behaves. For stateless recipes you do not even need a class: see FunctionTransformer in Feature Creation and Transformation.

The contract in four rules

init stores Only save parameters. No work, no checks.
fit learns Compute from training data, end names with an underscore, return self.
transform applies Use only what fit learned. Never refit.
Don't mutate Leave the input data and the parameters untouched.
1 / 2

A custom transformer

Our first transformer clips each column to percentiles learned in fit. That makes it a good example because it learns from training data (the limits), then applies them to any data. Using the training limits on new data is exactly what prevents leakage: the test rows never influence the bounds.

Python PercentileClipper: learns in fit, applies in transform

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The class has three methods and the base classes supply the rest: fit_transform comes from TransformerMixin, get_feature_names_out (one output name per input column, which also enables set_output) from OneToOneFeatureMixin, and get_params, set_params and the readable print(clip) come from BaseEstimator. validate_data converts the input to a checked array and remembers the number of features, so the same class later raises a clear error when transform receives the wrong number of columns. The order of the base classes matters: mixins go first, BaseEstimator last.

validate_data and check_is_fitted come from sklearn.utils.validation. Older tutorials use check_array and check_X_y instead; validate_data replaced the old helper methods in recent releases and also sets n_features_in_ and feature_names_in_ for you.

Rules for __init__ and parameters

get_params finds your parameters by reading the signature of __init__, then looking up an attribute with the same name. That gives three firm rules:

  1. Every __init__ argument is stored under the same name, unchanged: self.lower = lower.
  2. No logic in __init__: no validation, no conversion, no computed attributes. A search calls set_params later, which bypasses __init__, so any work done there would be skipped. Validate at the start of fit.
  3. Learned attributes end with an underscore and appear only after fit (low_, high_). The underscore is how scikit-learn tells hyperparameters from learned state, and how check_is_fitted knows whether fit has run.

Avoid mutable default values such as def __init__(self, cols=[]), and do not modify arguments in place.

Python What BaseEstimator gives you: params, clone and search

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The clone has no low_: clone builds a new object from get_params(), which is how cross-validation gets a fresh unfitted copy for every fold. If your class stored a computed value in __init__, the clone would not reproduce it, and that is why the rules above matter.

A custom classifier

A classifier follows the same shape: fit(X, y) learns and returns self, predict(X) returns labels. ClassifierMixin adds an accuracy-based score. Here is a nearest-centroid classifier. It stores the mean of each class and predicts the class whose mean is closest. The learned classes_ attribute is the convention for class labels.

Python A nearest-centroid classifier from scratch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Because the class passes the contract, cross_val_score can clone and refit it, and the score method needs no code of our own. For predict_proba you would add that method and, for a classifier, scikit-learn would then let metrics such as ROC AUC use it (Thresholds, ROC and Precision-Recall Curves).

Testing the contract

scikit-learn ships the same checks it runs on its own estimators. check_estimator runs dozens of them: does fit return self, do repeated fits give the same answer, are parameters untouched, are error messages sensible for bad input, does the class handle a single feature, and so on. Run it in your own test suite (the pytest helper is parametrize_with_checks).

Python Run the scikit-learn estimator checks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A small hand-written test still helps for your own logic: assert that fit returns self, that transform before fit raises NotFittedError, and that the output on a known tiny input matches a number you worked out by hand.

When not to write a class

  • A pure function with no learned state (log, ratio, date part): use FunctionTransformer.
  • Column-specific routing: use ColumnTransformer.
  • Something that needs the target to be transformed: use TransformedTargetRegressor.
  • Heavy research code: a plain function is faster to write. Wrap it in a class only when it must live inside a pipeline or a search.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where should a custom estimator validate its hyperparameters?

    set_params and clone bypass init, so validation there would be skipped. Validating at the start of fit always runs.
  2. 2. Which attribute name marks something learned from the data in fit?

    The trailing underscore is the convention for learned attributes. check_is_fitted uses it to know whether fit has run.
  3. 3. What must fit return?

    Returning self allows chaining such as est.fit(X).transform(X), and fit_transform from TransformerMixin relies on it.
  4. 4. What does clone(estimator) copy?

    clone creates a new unfitted object from get_params. Cross-validation uses it to get a fresh estimator for each fold.
  5. 5. A transformer stores self.factor = factor * 2 in init. What is the likely consequence?

    get_params returns the stored attribute, which differs from the argument given. clone then builds an object with a different value.

Summary

  • A custom estimator needs __init__ (store parameters only), fit (learn, set name_ attributes, return self) and transform or predict.
  • BaseEstimator supplies get_params, set_params and repr; TransformerMixin supplies fit_transform; ClassifierMixin supplies score. Put mixins first.
  • Use validate_data and check_is_fitted for input checks and clear errors.
  • No logic in __init__; validate in fit; learned attributes end with an underscore.
  • clone copies parameters, not learned state, so cross-validation and searches work with your class unchanged.
  • Test with check_estimator and small hand-checked examples.

Next: Clustering Basics.