FeatureSpec¶

class polars_learn.FeatureSpec(
    expression,
    *,
    alias=None,
    drop=None,
    name=None,
    verbosity=0,
)

Describe a native Polars feature operation.

Use this class to describe a reusable feature calculation for FeatureEngineer. Construction validates and stores the expressions; it does not execute them, fit on data, or implement transform. The engineer applies the expressions with Polars with_columns, then removes the configured drop columns. Existing columns can be replaced. Expressions within one specification read the same stage's input, so they cannot read columns newly created by siblings. Compose expressions directly from existing columns, or use later specifications for dependent features. The engineer applies specifications in the order you supply them.

Parameters¶

expression polars.Expr or sequence of polars.Expr

Single expression or nonempty sequence evaluated together, normalized to a tuple. Native output names are used unless alias is set. Sibling expressions cannot depend on outputs created within the same specification.

alias str or None, default=None

Override the output name of a single expression. Multiple expressions or an expression expanding to multiple outputs cannot use this option.

drop sequence of str or None, default=None

Columns to remove after evaluating the expressions. Missing names fail during execution; later specifications cannot use dropped columns.

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

Print validation summaries at 1 and output/drop details at 2.

name str or None, default=None

Descriptive label included in feature execution errors.

Attributes¶

expression tuple of polars.Expr

Canonical expression representation, including any explicit alias.

drop tuple of str

Columns to drop after evaluating this specification.

name str or None

Optional debugging label.

verbosity int

Configured diagnostic level, independent of the feature engineer.

Raises¶

TypeError

If expressions, drop columns, containers, or verbosity have invalid types.

ValueError

If the expression sequence is empty, an explicit alias is ambiguous, output names are duplicated, a label is invalid, or verbosity is outside the supported levels.

See also¶

FeatureEngineer: Execute an ordered sequence of specifications.

Notes¶

Existing columns may be overwritten deliberately. Expressions follow native Polars naming, so an additional alias is not required when the expression already has a determinable output name. Selector names and duplicates that depend on the input schema are resolved by the feature engineer. Expressions may contain map_elements or map_batches Python callbacks. Declare return_dtype for predictable schema checks and use pure functions with serializable state. Prefer native expressions for speed; callbacks and their dependencies must remain usable in the deployment environment. This class is an operation description, not a scikit-learn estimator. Its verbosity reports construction independently of an engineer's verbosity. Pickling preserves native expressions using Polars serialization, including Python callbacks with serializable state. Version mismatches emit InconsistentVersionWarning before state restoration. Compatible cross-version expressions are attempted using JSON; incompatible state raises SerializationError. Load trusted artifacts only and validate after upgrading.

Examples¶

>>> import polars as pl
>>> from polars_learn import FeatureSpec
>>> spec = FeatureSpec(pl.col("price") * pl.col("quantity"), alias="notional")
>>> spec.expression[0].meta.output_name()
'notional'

Methods¶

FeatureSpec is a description, not an estimator. It has no fit, transform, or prediction methods. Pass it to FeatureEngineer for execution.

See also¶

Shared estimator conventions · Production guidance · Persistence