polars-learn
Skip to content
polars-learnFeaturePassthrough

FeaturePassthrough

Reference

[source]
class polars_learn.FeaturePassthrough(
    columns,
    *,
    convert_pandas=False,
    warn_on_conversion=True,
    verbosity=0,
)

Pass explicitly selected columns through without changing their contents.

Use this transformer to retain a named subset of features that need no calculation, renaming, or casting. fit checks the selected names and records the layout; transform returns only those columns in the order you supply them. It inherits this selection behavior from ColumnSelector and exposes no rename option. Native Polars values and dtypes are preserved. In a sequential pipeline, unselected columns are removed. To combine these unchanged features with a separate transformed branch, use an eager ColumnTransformer. Choose ColumnSelector if you also need renaming.

Polars is the execution engine. Native DataFrames and LazyFrames are accepted; pandas input requires convert_pandas=True and is converted behind the scenes. Output is native Polars by default, including an eager Polars frame for converted pandas input. Use set_output(transform="pandas") for compatibility output; install polars-learn[pandas] for pandas and PyArrow. Lazy output defers row execution, while eager Polars or pandas output collects during transform. Prefer native Polars input/output for speed and to avoid conversion overhead.

Parameters

columns sequence of str

Nonempty ordered sequence of unique, nonempty column names to keep. Other input columns are omitted. A bare string is invalid.

convert_pandas bool, default=False

Permit pandas DataFrames and convert them to Polars. Some dtypes require PyArrow; install the pandas extra for both dependencies.

warn_on_conversion bool, default=True

Emit PandasConversionWarning on enabled pandas conversion, independently of verbosity.

verbosity {0, 1, 2}, default=0

Print progress at 1 and additional schema details at 2; 0 is silent.

Attributes

feature_names_in_ ndarray of str, dtype=object

All training input names in input order, including unselected columns.

n_features_in_ int

Number of all training input columns.

columns_ tuple of str

Selected source names recorded by fit.

output_features_ ndarray of str, dtype=object

Selected column names in the requested output order.

Raises

TypeError

If columns or common options have invalid types.

ValueError

If selected names are duplicated or verbosity is outside 0, 1, and 2. Fit and transform also reject missing selected columns.

See also

ColumnSelector: Select columns with optional renaming.

Notes

This is a scikit-learn transformer with inherited fit, transform, fit_transform, get_feature_names_out, get_params, set_params, and set_output. Fit checks that selected columns exist; transform requires fitting. Selected Polars values, names, dtypes, nulls, and row order are preserved. Input order and dtypes may change between calls; no dtype validation occurs. There is no renaming option. Refit after changing selected columns.

Default returns preserve input kind: DataFrame input returns DataFrame and LazyFrame input returns an unevaluated LazyFrame. set_output can force "polars" (eager), "polars-lazy", or "pandas" compatibility output. Inputs are never mutated. Source/schema-resolution and collection errors are not wrapped.

A sequential pipeline step returns only its selected columns. To retain them alongside columns transformed in another branch, use ColumnTransformer with eager input, a branch for each operation, and Polars output.

Examples

>>> import polars as pl
>>> from polars_learn import FeaturePassthrough
>>> X = pl.DataFrame({"id": [1, 2], "value": [3.0, 4.0]})
>>> keep = FeaturePassthrough(["id"])
>>> keep.fit_transform(X.lazy()).collect().to_dict(as_series=False)
{'id': [1, 2]}
>>> keep.get_feature_names_out().tolist()
['id']

Methods

Method Purpose
fit(X, y=None) Check selected columns and record input and output names.
transform(X) Select fitted columns, rename them, and verify output names.
fit_transform(X, y=None, **fit_params) Fit and transform the same input using the configured return kind.
get_feature_names_out(input_features=None) Return the fitted output column names.
get_params(deep=True) Get estimator constructor parameters.
set_params(**params) Set constructor parameters using scikit-learn conventions.
set_output(*, transform=None) Configure native Polars output or pandas compatibility output.

fit

[source]
fit(X, y=None)

Check selected columns and record input and output names.

Call before transforming to establish the selected output layout. Checks that all configured columns exist and records all input names plus the selected output names, including any renames. Extra input columns are allowed, input order may differ, and no training statistics are learned. This inherited method also fits FeaturePassthrough, which has no renames.

Parameters

X polars.DataFrame, polars.LazyFrame or pandas.DataFrame

Input containing every selected column. Other columns and a different input order are allowed. Pandas requires conversion enabled.

y object, default=None

Ignored; accepted for scikit-learn compatibility.

Returns

self ColumnSelector or FeaturePassthrough

The fitted selection transformer. Dtypes are not learned or validated.

Raises

TypeError

If input, options, or column/rename parameter types are unsupported.

ValueError

If configuration is invalid or selected columns are missing.

Notes

Lazy input is checked through schema metadata without collecting rows. Output configuration does not change the return from fit.

transform

[source]
transform(X)

Select fitted columns, rename them, and verify output names.

Call after fitting to prepare the selected model inputs. Selects columns in configured order, optionally renames them, and checks the resulting names against the fitted layout. Unselected columns are omitted; dtype changes are accepted. For FeaturePassthrough, selection is unchanged and no renames occur. The original input is never modified.

Output follows set_output: native Polars by default, eager Polars for "polars", a LazyFrame for "polars-lazy", or a pandas DataFrame for "pandas". Eager Polars and pandas output collect lazy rows. Pandas output uses Polars conversion defaults and may change dtype/null representation; missing pandas or PyArrow raises ImportError at conversion. Pandas input requires convert_pandas=True independently of the output choice.

Parameters

X polars.DataFrame, polars.LazyFrame or pandas.DataFrame

Input containing the selected fitted columns. Unselected columns are ignored; input order and dtypes may differ from fitting. Pandas requires conversion enabled.

Returns

X_selected polars.DataFrame, polars.LazyFrame or pandas.DataFrame

Selected columns in configured order, including renames. Default preserves input kind; set_output can force eager, lazy, or pandas output.

Raises

sklearn.exceptions.NotFittedError

If fit has not completed successfully.

TypeError

If input or parameter types are unsupported.

ValueError

If selected columns are missing, configuration is invalid, or renamed output names differ from fitting.

Notes

Lazy metadata errors occur now; source/value errors can occur when a returned plan is collected. Explicit eager output collects within this method. Source and collection errors are not wrapped.

fit_transform

[source]
fit_transform(
    X,
    y=None,
    **fit_params,
)

Fit and transform the same input using the configured return kind.

Convenience method for preparing training data: calls fit(X, y) and then transform(X) on the same input. This updates fitted state and returns the prepared frame. The target is ignored and extra fit parameters are unsupported. See fit for the class-specific learned contract and transform for validation and output behavior.

Output follows set_output: native Polars by default, eager Polars for "polars", a LazyFrame for "polars-lazy", or a pandas DataFrame for "pandas". Eager Polars and pandas output collect lazy rows. Pandas output uses Polars conversion defaults and may change dtype/null representation; missing pandas or PyArrow raises ImportError at conversion. Pandas input requires convert_pandas=True independently of the output choice.

Parameters

X polars.DataFrame, polars.LazyFrame or pandas.DataFrame

Input accepted by fit and transform. Pandas requires conversion enabled.

y object, default=None

Ignored; accepted for scikit-learn compatibility.

**fit_params dict

Extra fit parameters are unsupported and raise TypeError.

Returns

X_transformed polars.DataFrame, polars.LazyFrame or pandas.DataFrame

Transformed input. Default preserves input kind; set_output can force an eager DataFrame or LazyFrame. Converted pandas is eager.

See also

fit: Validate input and record fitted state. transform: Apply the fitted transformation and output configuration.

get_feature_names_out

[source]
get_feature_names_out(input_features=None)

Return the fitted output column names.

Use these names to label model inputs or inspect a fitted pipeline. Returns a copy of the names recorded during fitting; it does not transform data, collect lazy rows, or refit the transformer. Supplied input names are checked against all fitted input names in exact order. For SchemaValidator, inference-only extra columns are not included; this is the fitted contract rather than a live query's column list.

Parameters

input_features array-like of str or None, default=None

If supplied, names must exactly match feature_names_in_.

Returns

feature_names_out ndarray of shape (n_features_out_,), dtype=object

Copy of fitted output names. SchemaValidator excludes inference-only extras. SchemaSpec includes preserved training extras. A selector lists selected names, including any renames; a passthrough lists unchanged selected names. An engineer lists all output names.

Raises

sklearn.exceptions.NotFittedError

If the transformer has not been fitted.

ValueError

If supplied input names differ from fitted names or order.

get_params

[inherited API]
get_params(deep=True)

Get estimator constructor parameters.

Parameters

deep bool, default=True

Include nested estimator parameters when present.

Returns

params dict

Constructor parameters and, when requested, nested parameters. Output configuration is managed separately by set_output.

set_params

[inherited API]
set_params(**params)

Set constructor parameters using scikit-learn conventions.

Parameters

**params dict

Constructor parameter names and values. Nested estimator parameters use the step__parameter convention where supported.

Returns

self estimator instance

This estimator with updated configuration.

Raises

ValueError

If a parameter name is unknown.

Notes

Changing parameters does not immediately validate configuration or clear fitted attributes. Refit after contract changes. Invalid parameter values fail at the next relevant fit or transform operation.

set_output

[source]
set_output(*, transform=None)

Configure native Polars output or pandas compatibility output.

Call this when a downstream consumer needs a particular frame container. It only stores a choice for subsequent transform/fit_transform calls; it does not fit, transform, or collect data at configuration time. Use "default" to follow each call's input kind, "polars" for eager Polars, "polars-lazy" for a lazy plan, or "pandas" for an eager pandas DataFrame. Converted pandas input is treated as eager Polars by default. Pandas input permission remains separate: enable convert_pandas on any transformer receiving pandas, even when pandas output is requested.

Parameters

transform {"default", "polars", "polars-lazy", "pandas"} or None, default=None

Default preserves the input kind. "polars" collects an eager DataFrame; "polars-lazy" returns a LazyFrame. None leaves the configuration unchanged. "pandas" collects if necessary and converts the result to a pandas DataFrame. Requires the pandas extra.

Returns

self estimator instance

This transformer.

Raises

ValueError

If an unsupported output container is requested.

Notes

Prefer native Polars output for speed and to avoid conversion overhead. Pandas output is provided for compatibility and uses Polars to_pandas defaults, including a fresh RangeIndex and dtype/null conversion. Conversion raises ImportError if pandas or PyArrow is unavailable. Input conversion remains separately controlled by convert_pandas. Automatic scikit-learn output wrapping and global output settings are bypassed to preserve native names and permitted extra columns. Output choices survive cloning. None leaves the current choice intact; "default" resets input-kind preservation. Fit always returns self and does not collect lazy rows. Forcing lazy output from eager input may wrap an already evaluated result; use lazy input to defer evaluation.

See also

Shared estimator conventions · Production guidance · Persistence

Concepts and worked workflows.