polars-learn
Skip to content
polars-learnColumnSelector

ColumnSelector

Reference

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

Select and optionally rename columns in a Polars DataFrame or LazyFrame.

Use this transformer to define the exact feature names and column order passed to a model. fit checks selected names and records the layout; transform selects those columns in the supplied order, applies optional renames, and checks the output names against fitting. Other columns are omitted. Values are unchanged and dtypes are not validated or cast. Choose FeaturePassthrough when renaming is unnecessary, or add a schema validator when input dtypes must be enforced.

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 input column names to keep.

rename dict of str to str, default=None

Optional mapping from selected source names to nonempty output names. Final output names, including unchanged names, must remain unique.

convert_pandas bool, default=False

Allow pandas DataFrames and convert them to Polars. Requires pandas; some dtypes also require PyArrow.

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

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

warn_on_conversion bool, default=True

Emit PandasConversionWarning when converting pandas input.

Attributes

feature_names_in_ ndarray of str, dtype=object

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

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 output names after renaming, in selection order.

Raises

TypeError

If columns, rename, or common options have invalid types.

ValueError

If selected or final renamed names are duplicated, rename keys are unselected, or verbosity is outside 0, 1, and 2.

See also

SchemaSpec: Validate explicit required dtypes before selecting columns. FeaturePassthrough: Explicit unchanged-column selection without renaming.

Notes

DataFrames return DataFrames and LazyFrames return unevaluated LazyFrames by default. Use set_output to force eager, lazy, or pandas output.

Examples

>>> import polars as pl
>>> from polars_learn import ColumnSelector
>>> X = pl.DataFrame({"a": [1], "b": [2]})
>>> selector = ColumnSelector(["b"], rename={"b": "value"})
>>> selector.fit_transform(X.lazy()).collect().columns
['value']

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.