SciKeras: Scikit-Learn API wrapper for Keras

SciKeras is a Scikit-Learn wrapper for Keras/TensorFlow. It provides a Keras-based model with a standard Scikit-Learn interface, allowing you to use Keras models within Scikit-Learn workflows (such as GridSearchCV, Pipeline, or cross_val_score).

It is designed to be the successor to the deprecated keras.wrappers.scikit_learn and offers significant improvements over the original TensorFlow implementation. If you are already familiar with both Scikit-Learn and Keras, SciKeras follows their standard syntax and mental models without requiring you to learn new concepts.

In the original TensorFlow wrappers, fit() returned a Keras History object. To comply with the Scikit-Learn API, SciKeras's fit() method returns the estimator instance (self) instead.

To access training logs, use the history_ attribute on the fitted estimator. Note that SciKeras normalizes metric names (e.g., "mae" becomes "mean_absolute_error").

• fit(): Resets the history_ attribute.
• partial_fit(): Extends the history_ attribute.

   def get_model():
      ...
      model.compile(loss="mse", metrics=["mae"])
      return model

   clf = KerasClassifier(get_model)
-  hist = clf.fit(...).history
-  losses = hist["mae"]
+  hist = clf.fit(...).history_
+  losses = hist["mean_absolute_error"]

SciKeras natively supports sparse inputs for features (X). You do not need to perform any special configuration or transformations to enable sparse support; you can simply pass a sparse matrix (e.g., from scipy.sparse) directly to the .fit() method of a SciKeras wrapper like KerasRegressor or KerasClassifier.

Using sparse inputs is particularly effective when dealing with high-cardinality categorical features that have been one-hot encoded, as it significantly reduces peak memory consumption compared to dense representations.

from scikeras.wrappers import KerasRegressor
# Assuming X is a scipy sparse matrix
model = KerasRegressor(model=get_clf, loss='mse', epochs=5)
model.fit(X, y)

When you instantiate KerasClassifier or KerasRegressor, arguments are stored unmodified and the model remains uninstantiated. This allows for safe cloning (e.g., in GridSearchCV).

Attributes are only initialized when .fit() or .initialize() is called. Following Scikit-Learn convention, initialized attributes end with an underscore (e.g., model_).

SciKeras does not support tf.data.Dataset objects directly.

This limitation exists because SciKeras adheres strictly to the Scikit-Learn API, and Scikit-Learn's API is designed for in-memory data structures (like NumPy arrays or SciPy sparse matrices) rather than the lazy-evaluation model used by TensorFlow Datasets.

If your workflow requires the performance and scalability of tf.data.Dataset, you should use TensorFlow/Keras directly instead of using the SciKeras wrappers.

SciKeras uses a data transformer interface to reconcile scikit-learn's expected data formats (2D arrays for X, 1D arrays for y) with Keras's ability to handle multiple inputs, multiple outputs, and higher-dimensional tensors.

This is achieved via two scikit-learn transformers:

1. feature_encoder: Transforms the input features (X).
2. target_encoder: Transforms the target labels/values (y).

During the fit lifecycle, SciKeras calls fit_transform on both encoders before passing the data to the Keras model. During predict, it applies transform to X and inverse_transform to the model's predictions to return data in the original scikit-learn format.

To maintain Scikit-Learn compatibility, TensorFlow Dataset inputs are not supported.

Inputs must be converted to one of the following formats before being passed to SciKeras or a Scikit-Learn pipeline:

• NumPy arrays
• Pandas DataFrames
• Lists

When defining a model building function for KerasClassifier or KerasRegressor, you can include a meta parameter. SciKeras automatically injects a dictionary containing metadata discovered during the fit call.

Commonly used keys in meta include:

• n_features_in_: The number of input features (useful for defining the Input layer shape).
• n_classes_: The number of classes (useful for defining the output layer size in classification).
• target_type_: The type of task (e.g., 'binary' or 'multiclass').

Example of using meta to define input shape:

from typing import Dict, Any
import keras

def get_clf_model(meta: Dict[str, Any]):
    model = keras.Sequential()
    # Use n_features_in_ from meta to size the input layer
    inp = keras.layers.Input(shape=(meta["n_features_in_"],))
    model.add(inp)
    return model