Skip to content

Features

features

Feature definitions: the immutable output of phase 1.

Features are frozen dataclasses with structural equality, so a feature reached by two different routes deduplicates in a set with no extra bookkeeping. Every dtype here is derived from primitive metadata, never from data.

Feature

Feature dataclass 

Feature()

Bases: ABC

Base class for every feature definition.

name abstractmethod property 

name

The column name in the feature matrix.

A plain SQL identifier: parts are joined with __ rather than the dots, parentheses and spaces a conventional DFS name uses, since a backend that generates SQL parses those as table qualifiers and function calls rather than as part of an identifier. See :attr:display_name for the readable form.

display_name abstractmethod property 

display_name

The readable name, e.g. MEAN(transactions.amount).

Carries the same meaning as :attr:name in the conventional DFS notation. Used for documentation, logging and error messages; never as a column name.

dtype abstractmethod property 

dtype

Output dtype, computed statically.

depth abstractmethod property 

depth

Number of stacked primitive applications.

table abstractmethod property 

table

Table this feature is a column of.

base_features abstractmethod property 

base_features

Features this one is computed from.

output_names property 

output_names

One column name per output; more than one for multi-output primitives.

display_output_names property 

display_output_names

One readable name per output, parallel to :attr:output_names.

is_multi_output property 

is_multi_output

Whether this feature materializes more than one column.

Only the indexed names in :attr:output_names are ever materialized, so a multi-output feature has no single column another primitive could read. It is a valid output of synthesis but never a valid input.

Deriving this from :attr:output_names rather than from a primitive's number_of_outputs keeps it well defined for :class:IdentityFeature and :class:DirectFeature, which have no primitive at all.

Feature kinds

IdentityFeature dataclass 

IdentityFeature(table_name, column, column_dtype)

Bases: Feature

A raw column of a table.

Attributes:

Name Type Description
table_name str

Table the column belongs to.
column str

Column name.
column_dtype Any

The column's narwhals dtype.

table_name instance-attribute 

table_name

column instance-attribute 

column

column_dtype instance-attribute 

column_dtype

name property 

name

The column's own name.

display_name property 

display_name

A raw column reads the same either way.

dtype property 

dtype

The column's dtype.

depth property 

depth

Identity features are depth zero.

table property 

table

Table the column belongs to.

base_features property 

base_features

Identity features have no bases.

DirectFeature dataclass 

DirectFeature(base_feature, relationship)

Bases: Feature

A parent's feature joined down onto the child.

Attributes:

Name Type Description
base_feature Feature

The feature on the parent table.
relationship Relationship

The parent-child link being traversed.

base_feature instance-attribute 

base_feature

relationship instance-attribute 

relationship

name property 

name

Generated name, e.g. customers__age.

display_name property 

display_name

Readable name, e.g. customers.age.

dtype property 

dtype

The parent feature's dtype, unchanged.

depth property 

depth

One deeper than the parent feature.

table property 

table

The child table the value lands on.

base_features property 

base_features

The single parent feature.

TransformFeature dataclass 

TransformFeature(primitive, bases)

Bases: Feature

A primitive applied row-wise to features of one table.

Attributes:

Name Type Description
primitive Primitive

The transform primitive.
bases tuple[Feature, ...]

Input features, all on the same table.

primitive instance-attribute 

primitive

bases instance-attribute 

bases

name property 

name

Generated name, e.g. MONTH__started_at.

display_name property 

display_name

Readable name, e.g. MONTH(started_at).

dtype property 

dtype

Dtype derived from the primitive and its inputs.

depth property 

depth

One deeper than the deepest input.

table property 

table

The table its inputs live on.

base_features property 

base_features

Its input features.

output_names property 

output_names

One name per output column.

display_output_names property 

display_output_names

One readable name per output column.

GroupByTransformFeature dataclass 

GroupByTransformFeature(primitive, bases, relationship)

Bases: Feature

A transform applied within groups defined by a foreign key.

Attributes:

Name Type Description
primitive Primitive

The transform primitive.
bases tuple[Feature, ...]

Input features on the child table.
relationship Relationship

The link whose foreign key defines the groups.

primitive instance-attribute 

primitive

bases instance-attribute 

bases

relationship instance-attribute 

relationship

name property 

name

Generated name, e.g. CUM_SUM__amount__by__session_id.

display_name property 

display_name

Readable name, e.g. CUM_SUM(amount) by session_id.

dtype property 

dtype

Dtype derived from the primitive and its inputs.

depth property 

depth

One deeper than the deepest input.

table property 

table

The child table the values land on.

base_features property 

base_features

Its input features.

output_names property 

output_names

One name per output column.

display_output_names property 

display_output_names

One readable name per output column.

AggregationFeature dataclass 

AggregationFeature(primitive, bases, relationship)

Bases: Feature

A primitive applied to a child table's rows, grouped by foreign key.

Attributes:

Name Type Description
primitive Primitive

The aggregation primitive.
bases tuple[Feature, ...]

Input features on the child table. Empty for zero-arity primitives such as count.
relationship Relationship

The parent-child link being aggregated across.

primitive instance-attribute 

primitive

bases instance-attribute 

bases

relationship instance-attribute 

relationship

name property 

name

Generated name, e.g. MEAN__transactions__amount.

Zero-arity primitives name the child table instead of a column, giving COUNT__transactions.

display_name property 

display_name

Readable name, e.g. MEAN(transactions.amount).

dtype property 

dtype

Dtype derived from the primitive and its inputs.

depth property 

depth

One deeper than the deepest input; 1 when there are none.

table property 

table

The parent table the aggregate lands on.

base_features property 

base_features

Its input features on the child table.

output_names property 

output_names

One name per output column.

display_output_names property 

display_output_names

One readable name per output column.