polars-learn
Skip to content
polars-learnValueValidator

ValueValidator

ValueValidator applies named row-level Boolean expressions to catch nulls, bounds, and allowed-value violations before data reaches model features. Add it after a schema component when both structural and value contracts matter. See the value validation guide for composition and lazy execution details.

Reference

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

Reject rows that fail named Boolean Polars expressions.

Use this transformer after structural schema validation for row-level rules such as non-null requirements, bounds, and allowed-value checks. Every check must produce one Boolean value per row. False and null results are violations. The input is returned unchanged when all checks pass.

Parameters

checks dict of str to polars.Expr

Nonempty mapping from diagnostic labels to row-wise Boolean expressions. For example, {"positive_price": pl.col("price") > 0}.

convert_pandas bool, default=False

Allow pandas DataFrames and convert them to Polars.

warn_on_conversion bool, default=True

Emit PandasConversionWarning when converting pandas input.

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

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

Attributes

feature_names_in_ ndarray of str, dtype=object

Input column names and order recorded during fit.

n_features_in_ int

Number of input columns recorded during fit.

output_features_ ndarray of str, dtype=object

Input column names, unchanged by validation.

Raises

TypeError

If checks, expressions, or common options have invalid types.

ValueError

If checks are empty, labels are invalid, or expressions do not resolve to Boolean values on the fitted schema.

ValueValidationError

If an input schema differs from fitting, checks cannot execute, or any check returns false or null for one or more rows.

sklearn.exceptions.NotFittedError

If transform is called before a successful fit.

Notes

fit resolves the check expressions against schema metadata only; it never evaluates row values. transform evaluates the checks once. Lazy inputs are materialized during transform so rule violations fail before it returns and default output can preserve the lazy container using an in-memory frame. Value checks do not add columns, mutate input, or change row order.

Examples

>>> import polars as pl
>>> from polars_learn import ValueValidator
>>> frame = pl.DataFrame({"price": [2.0, 3.0], "quantity": [1, 2]})
>>> checks = {
...     "positive_price": pl.col("price") > 0,
...     "nonnegative_quantity": pl.col("quantity") >= 0,
... }
>>> validator = ValueValidator(checks)
>>> validator.fit_transform(frame).equals(frame)
True

Methods

Method Purpose
fit(X, y=None) Resolve checks against the input schema without evaluating rows.
transform(X) Validate fitted input names, order, dtypes, and configured values.
fit_transform(X, y=None, **fit_params) Fit the schema contract, validate values, and return the input.
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)

Resolve checks against the input schema without evaluating rows.

transform

[source]
transform(X)

Validate fitted input names, order, dtypes, and configured values.

fit_transform

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

Fit the schema contract, validate values, and return the input.

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