ENH: Renames CallableTransformer -> FunctionTransformer.

Makes `pass_y` an argument to FunctionTransformer to indicate that the
labels should be passed to the wrapped function.

Author: amueller

doc/modules/classes.rst

@@ -1104,7 +1104,7 @@ See the :ref:`metrics` section of the user guide for further details.
    :template: class.rst
 
    preprocessing.Binarizer
-   preprocessing.CallableTransformer
+   preprocessing.FunctionTransformer
    preprocessing.Imputer
    preprocessing.KernelCenterer
    preprocessing.LabelBinarizer

doc/modules/preprocessing.rst

@@ -514,17 +514,17 @@ Custom Transformers
 
 Often, you will want to convert an existing python function into a transformer
 to assist in data cleaning or processing. Users may implement a transformer from
-an arbitrary callable with :class:`CallableTransformer`. For example, one could
+an arbitrary function with :class:`FunctionTransformer`. For example, one could
 apply a log transformation in a pipeline like::
 
     >>> import numpy as np
-    >>> from sklearn.preprocessing import CallableTransformer
-    >>> transformer = CallableTransformer(np.log)
+    >>> from sklearn.preprocessing import FunctionTransformer
+    >>> transformer = FunctionTransformer(np.log)
     >>> X = np.array([[1, 2], [3, 4]])
     >>> transformer.transform(X)
     array([[ 0.        ,  0.69314718],
            [ 1.09861229,  1.38629436]])
 
-For a full code example that demonstrates using a :class:`CallableTransformer`
+For a full code example that demonstrates using a :class:`FunctionTransformer`
 to do column selection,
-see :ref:`example_preprocessing_plot_callable_transformer.py`
+see :ref:`example_preprocessing_plot_function_transformer.py`

examples/preprocessing/plot_callable_transformer.py renamed to examples/preprocessing/plot_function_transformer.py

@@ -1,11 +1,11 @@
 """
 =========================================================
-Using CallableTransformer to select columns
+Using FunctionTransformer to select columns
 =========================================================
 
-Shows how to use a callable transformer in a pipeline. If you know your
+Shows how to use a function transformer in a pipeline. If you know your
 dataset's first principle component is irrelevant for a classification task,
-you can use the CallableTransformer to select all but the first column of the
+you can use the FunctionTransformer to select all but the first column of the
 PCA transformed data.
 """
 import matplotlib.pyplot as plt
@@ -14,7 +14,7 @@
 from sklearn.cross_validation import train_test_split
 from sklearn.decomposition import PCA
 from sklearn.pipeline import make_pipeline
-from sklearn.preprocessing import CallableTransformer
+from sklearn.preprocessing import FunctionTransformer
 
 
 def _generate_vector(shift=0.5, noise=15):
@@ -38,7 +38,7 @@ def generate_dataset():
     )), np.hstack((np.zeros(1000), np.ones(1000)))
 
 
-def all_but_first_column(X, y):
+def all_but_first_column(X):
     return X[:, 1:]
 
 
@@ -48,7 +48,7 @@ def drop_first_component(X, y):
     transform the dataset.
     """
     pipeline = make_pipeline(
-        PCA(), CallableTransformer(all_but_first_column),
+        PCA(), FunctionTransformer(all_but_first_column),
     )
     X_train, X_test, y_train, y_test = train_test_split(X, y)
     pipeline.fit(X_train, y_train)

sklearn/preprocessing/__init__.py

@@ -3,7 +3,7 @@
 normalization, binarization and imputation methods.
 """
 
-from .callable_transformer import CallableTransformer
+from .function_transformer import FunctionTransformer
 
 from .data import Binarizer
 from .data import KernelCenterer
@@ -33,7 +33,7 @@
 
 __all__ = [
     'Binarizer',
-    'CallableTransformer',
+    'FunctionTransformer',
     'Imputer',
     'KernelCenterer',
     'LabelBinarizer',

sklearn/preprocessing/callable_transformer.py renamed to sklearn/preprocessing/function_transformer.py

@@ -2,34 +2,43 @@
 from ..utils import check_array
 
 
-class CallableTransformer(BaseEstimator, TransformerMixin):
-    """Allows the construction of a transformer from an arbitrary callable.
+def _identity(X):
+    """The identity function.
+    """
+    return X
+
+
+class FunctionTransformer(BaseEstimator, TransformerMixin):
+    """Constructs a transformer from an arbitrary callable.
+
+    Note: If a lambda is used as the function, then the resulting
+    transformer will not be pickleable.
 
     Parameters
     ----------
     func : callable, optional default=None
         The callable to use for the transformation. This will be passed
         the same arguments as transform, with args and kwargs forwarded.
         If func is None, then func will be the identity function.
+
     validate : bool, optional default=True
         Indicate that the input X array should be checked before calling
         func. If validate is false, there will be no input validation.
+
     accept_sparse : boolean, optional
         Indicate that func accepts a sparse matrix as input.
-    args : tuple, optional
-        A tuple of positional arguments to be passed to func. These will
-        be passed after X and y.
-    kwargs : dict, optional
-        A dictionary of keyword arguments to be passed to func.
+
+    pass_y: bool, optional default=False
+        Indicate that transform should forward the y argument to the
+        inner callable.
 
     """
-    def __init__(self, func=None, validate=True, accept_sparse=False,
-                 args=None, kwargs=None):
+    def __init__(self, func=None, validate=True,
+                 accept_sparse=False, pass_y=False):
         self.func = func
         self.validate = validate
         self.accept_sparse = accept_sparse
-        self.args = args
-        self.kwargs = kwargs
+        self.pass_y = pass_y
 
     def fit(self, X, y=None):
         if self.validate:
@@ -39,6 +48,5 @@ def fit(self, X, y=None):
     def transform(self, X, y=None):
         if self.validate:
             X = check_array(X, self.accept_sparse)
-        return (self.func or (lambda X, y, *args, **kwargs: X))(
-            X, y, *(self.args or ()), **(self.kwargs or {})
-        )
+
+        return (self.func or _identity)(X, *((y,) if self.pass_y else ()))

sklearn/preprocessing/tests/test_callable_transformer.py renamed to sklearn/preprocessing/tests/test_function_transformer.py

@@ -1,7 +1,7 @@
 from nose.tools import assert_equal
 import numpy as np
 
-from ..callable_transformer import CallableTransformer
+from ..function_transformer import FunctionTransformer
 
 
 def _make_func(args_store, kwargs_store, func=lambda X, *a, **k: X):
@@ -16,20 +16,20 @@ def _func(X, *args, **kwargs):
 
 def test_delegate_to_func():
     # (args|kwargs)_store will hold the positional and keyword arguments
-    # passed to the function inside the CallableTransformer.
+    # passed to the function inside the FunctionTransformer.
     args_store = []
     kwargs_store = {}
     X = np.arange(10).reshape((5, 2))
     np.testing.assert_array_equal(
-        CallableTransformer(_make_func(args_store, kwargs_store)).transform(X),
+        FunctionTransformer(_make_func(args_store, kwargs_store)).transform(X),
         X,
         'transform should have returned X unchanged',
     )
 
-    # The function should only have recieved X and y, where y is None.
+    # The function should only have recieved X.
     assert_equal(
         args_store,
-        [X, None],
+        [X],
         'Incorrect positional arguments passed to func: {args}'.format(
             args=args_store,
         ),
@@ -42,38 +42,42 @@ def test_delegate_to_func():
         ),
     )
 
+    # reset the argument stores.
+    args_store.clear()
+    kwargs_store.clear()
+    y = object()
 
-def test_argument_closure():
-    # (args|kwargs)_store will hold the positional and keyword arguments
-    # passed to the function inside the CallableTransformer.
-    args_store = []
-    kwargs_store = {}
-    args = (object(), object())
-    kwargs = {'a': object(), 'b': object()}
-    X = np.arange(10).reshape((5, 2))
     np.testing.assert_array_equal(
-        CallableTransformer(
+        FunctionTransformer(
             _make_func(args_store, kwargs_store),
-            args=args,
-            kwargs=kwargs,
-        ).transform(X),
+            pass_y=True,
+        ).transform(X, y),
         X,
         'transform should have returned X unchanged',
     )
 
-    # The function should have been passed X, y (None), and the args
-    # that were passed to the CallableTransformer.
+    # The function should have recieved X and y.
     assert_equal(
         args_store,
-        [X, None] + list(args),
+        [X, y],
         'Incorrect positional arguments passed to func: {args}'.format(
             args=args_store,
         ),
     )
     assert_equal(
         kwargs_store,
-        kwargs,
-        'Incorrect keyword arguments passed to func: {args}'.format(
+        {},
+        'Unexpected keyword arguments passed to func: {args}'.format(
             args=kwargs_store,
         ),
     )
+
+
+def test_np_log():
+    X = np.arange(10).reshape((5, 2))
+
+    # Test that the numpy.log example still works.
+    np.testing.assert_array_equal(
+        FunctionTransformer(np.log).transform(X),
+        np.log(X),
+    )

sklearn/utils/estimator_checks.py

@@ -139,7 +139,7 @@ def _yield_transformer_checks(name, Transformer):
         yield check_transformer_data_not_an_array
     # these don't actually fit the data, so don't raise errors
     if name not in ['AdditiveChi2Sampler', 'Binarizer',
-                    'Normalizer', 'CallableTransformer']:
+                    'FunctionTransformer', 'Normalizer']:
         # basic tests
         yield check_transformer_general
         yield check_transformers_unfitted