scikit-learn¶

sklearn ¶

scikit-learn estimators for deep feature synthesis.

:class:DFSTransformer runs synthesis as a pipeline step. :class:DFSSelectorTransformer additionally drops the features a selector did not keep, so later calls compute only the rest. :class:dtype_selector picks columns by dtype for a ColumnTransformer.

Requires the sklearn extra: pip install "tusk[sklearn]". :mod:tusk does not import this package, so it must be imported by name.

dtype_selector ¶

dtype_selector(family)

Select columns by :class:~tusk.dtypes.DtypeFamily, on any backend.

Serves the same role as scikit-learn's make_column_selector, but reads the schema through narwhals, so it works on every backend a tusk database can use rather than pandas alone.

Families are :class:~tusk.dtypes.DtypeFamily values, so "string" means here what it means to a primitive: String, not Categorical or Enum.

Being a callable, it re-evaluates against whatever frame it is given, so a narrowed matrix narrows the selection.

Attributes:

Name	Type	Description
`family`	`DtypeFamily`	The :class:`~tusk.dtypes.DtypeFamily` to select.

Create a selector for one dtype family.

Parameters:

Name	Type	Description	Default
`family`	`DtypeFamily \| str`	A `DtypeFamily` or its string value, such as `"numeric"` or `"string"`. An unrecognized string raises `ValueError` listing the valid values.	required

family `instance-attribute` ¶

family = DtypeFamily(family)

DFSSelectorTransformer ¶

DFSSelectorTransformer(
    target_table,
    selection_pipeline=None,
    agg_primitives=None,
    trans_primitives=None,
    groupby_trans_primitives=None,
    max_depth=2,
    cutoff_time=None,
    output_backend=None,
)

Bases: DFSTransformer

DFS whose feature list is dropped to what a selector actually kept.

The point is inference cost. A run that generates eight hundred features and keeps forty should compute forty when it next sees data, not eight hundred.

Two column spaces meet here and must never be conflated: tusk space, the matrix, indexed by feature output_names, and encoded space, the encoder's output, indexed by get_feature_names_out(). The selector's mask indexes encoded space, pruning happens in tusk space, and sentinel lineage is the only bridge between them.

Fitting adds encoder_, the encoder prefix refitted on the kept columns; kept_names_, the encoded-space names the selector chose, in encoder order; and sentinels_, the renaming that recovers lineage. Like the parent's fitted attributes, none is declared at class level: all three are only known once :meth:fit has run.

Configure synthesis and selection.

Parameters:

Name	Type	Description	Default
`target_table`	`str`	Table to build features for.	required
`selection_pipeline`	`Any`	An estimator ending in a `SelectorMixin`; everything before it encodes.	`None`
`agg_primitives`	`Iterable[str \| Primitive] \| None`	Aggregation primitives; None selects the defaults.	`None`
`trans_primitives`	`Iterable[str \| Primitive] \| None`	Transform primitives; None selects the defaults.	`None`
`groupby_trans_primitives`	`Iterable[str \| Primitive] \| None`	Transforms within foreign-key groups.	`None`
`max_depth`	`int`	Maximum stacked primitive applications.	`2`
`cutoff_time`	`datetime \| None`	Only rows at or before this are visible.	`None`
`output_backend`	`str \| None`	Backend to collect to; None collects natively.	`None`

selection_pipeline `instance-attribute` ¶

selection_pipeline = selection_pipeline

fit ¶

fit(X, y=None, database=None)

Synthesize features, fit the selection pipeline, drop the rest.

Parameters:

Name	Type	Description	Default
`X`	`Any`	The target's primary key.	required
`y`	`Any`	Training targets, passed to the selector.	`None`
`database`	`Database \| None`	The database, routed as metadata.	`None`

Returns:

Type	Description
`DFSSelectorTransformer`	This estimator.

Raises:

Type	Description
`SchemaError`	If selection eliminated every feature.
`LineageError`	If a kept column vanished from the refitted encoder, meaning lineage missed a source and a feature was wrongly dropped.

Warns:

Type	Description
`LineageWarning`	If any kept column's provenance was unrecoverable, in which case nothing is dropped.
`UnencodedFeatureWarning`	If a feature fed no encoded column at all, so the encoder never gave the selector a chance to keep it.

transform ¶

transform(X, database=None)

Compute the kept features, encode them, apply the frozen mask.

Parameters:

Name	Type	Description	Default
`X`	`Any`	The target's primary key.	required
`database`	`Database \| None`	The database, routed as metadata.	`None`

Returns:

Type	Description
`Any`	The encoded, selected matrix.

get_feature_names_out ¶

get_feature_names_out(input_features=None)

Selected column names, with sentinels substituted back.

Parameters:

Name	Type	Description	Default
`input_features`	`Any`	Ignored; present for the scikit-learn signature.	`None`

Returns:

Type	Description
`ndarray`	Readable names such as `oh__MODE__transactions__category_a`.

DFSTransformer ¶

DFSTransformer(
    target_table,
    agg_primitives=None,
    trans_primitives=None,
    groupby_trans_primitives=None,
    max_depth=2,
    cutoff_time=None,
    output_backend=None,
)

Bases: TransformerMixin, BaseEstimator

Deep feature synthesis as a pipeline step.

:meth:fit sets features_, the synthesized definitions as a :class:~tusk.FeatureList, and database_, the database it was given. :meth:transform computes those features for the keys in X, returning one row per key in key order.

Configure synthesis.

Parameters:

Name	Type	Description	Default
`target_table`	`str`	Table to build features for.	required
`agg_primitives`	`Iterable[str \| Primitive] \| None`	Aggregation primitives; None selects the defaults.	`None`
`trans_primitives`	`Iterable[str \| Primitive] \| None`	Transform primitives; None selects the defaults.	`None`
`groupby_trans_primitives`	`Iterable[str \| Primitive] \| None`	Transforms within foreign-key groups.	`None`
`max_depth`	`int`	Maximum stacked primitive applications.	`2`
`cutoff_time`	`datetime \| None`	Only rows at or before this are visible.	`None`
`output_backend`	`str \| None`	Backend to collect the matrix to. None collects to the database's own backend.	`None`

target_table `instance-attribute` ¶

target_table = target_table

agg_primitives `instance-attribute` ¶

agg_primitives = agg_primitives

trans_primitives `instance-attribute` ¶

trans_primitives = trans_primitives

groupby_trans_primitives `instance-attribute` ¶

groupby_trans_primitives = groupby_trans_primitives

max_depth `instance-attribute` ¶

max_depth = max_depth

cutoff_time `instance-attribute` ¶

cutoff_time = cutoff_time

output_backend `instance-attribute` ¶

output_backend = output_backend

fit ¶

fit(X, y=None, database=None)

Synthesize feature definitions from the database's schema.

Reads no rows; :meth:transform does the computation.

Parameters:

Name	Type	Description	Default
`X`	`Any`	Ignored. Synthesis depends only on the schema.	required
`y`	`Any`	Ignored; present for the scikit-learn signature.	`None`
`database`	`Database \| None`	The database, routed as metadata.	`None`

Returns:

Type	Description
`DFSTransformer`	This estimator.

Raises:

Type	Description
`SchemaError`	If no database was supplied.

transform ¶

transform(X, database=None)

Compute the feature matrix for the keys in X.

Parameters:

Name	Type	Description	Default
`X`	`Any`	The target's primary key. Its order becomes the matrix's row order.	required
`database`	`Database \| None`	The database, routed as metadata. When absent, the one seen at fit is used.	`None`

Returns:

Type	Description
`Any`	An eager native frame, one row per key, in key order.

fit_transform ¶

fit_transform(X, y=None, database=None, **kwargs)

Fit, then transform, passing database to both.

Parameters:

Name	Type	Description	Default
`X`	`Any`	The target's primary key.	required
`y`	`Any`	Ignored.	`None`
`database`	`Database \| None`	The database, routed as metadata.	`None`
`**kwargs`	`Any`	Ignored; absorbs scikit-learn's fit parameters.	`{}`

Returns:

Type	Description
`Any`	The feature matrix.

get_feature_names_out ¶

get_feature_names_out(input_features=None)

Column names of the matrix, in column order.

A multi-output primitive contributes several names, so this is wider than len(features_).

Parameters:

Name	Type	Description	Default
`input_features`	`Any`	Ignored; present for the scikit-learn signature.	`None`

Returns:

Type	Description
`ndarray`	The names, as an object array.

scikit-learn¶

sklearn ¶

dtype_selector ¶

family instance-attribute ¶

DFSSelectorTransformer ¶

selection_pipeline instance-attribute ¶

fit ¶

transform ¶

get_feature_names_out ¶

DFSTransformer ¶

target_table instance-attribute ¶

agg_primitives instance-attribute ¶

trans_primitives instance-attribute ¶

groupby_trans_primitives instance-attribute ¶

max_depth instance-attribute ¶

cutoff_time instance-attribute ¶

output_backend instance-attribute ¶

fit ¶

transform ¶

fit_transform ¶

get_feature_names_out ¶

family `instance-attribute` ¶

selection_pipeline `instance-attribute` ¶

target_table `instance-attribute` ¶

agg_primitives `instance-attribute` ¶

trans_primitives `instance-attribute` ¶

groupby_trans_primitives `instance-attribute` ¶

max_depth `instance-attribute` ¶

cutoff_time `instance-attribute` ¶

output_backend `instance-attribute` ¶