Calculated Features (Business Rules)

Deterministic, rule-based columns computed from other columns after synthesis. See the usage guide for concepts, configuration format, and per-synthesizer examples.

CalculatedFeature

ydata.synthesizers.calculated_features.CalculatedFeature

A column (or set of columns) computed deterministically from other columns.

Calculated features — also known as business rules — express relationships that must hold exactly (arithmetic identities, sign conventions, denormalized copies) and are therefore computed with a user-provided Python function instead of being learned or generated. Supported by RegularSynthesizer, TimeSeriesSynthesizer, MultiTableSynthesizer and LLMSynthesizer through their fit(calculated_features=...) argument, using table_name.column_name addressing.

Parameters:

Name	Type	Description	Default
features	str | list[str]	Output column(s), e.g. "dsa.vat_value" or a list of outputs. All outputs of one feature must belong to the same table.	required
function	Callable	Callable receiving one pandas.Series per calculated_from entry (positionally). For a single output it returns a Series or 1-D array; for multiple outputs a tuple/list of Series, a 2-D array, or a DataFrame with one column per output.	required
calculated_from	list[str] | str	Input column(s), in the order the function expects them.	required
reference_keys	dict[str, list | str] | None	Required only for cross-table features — a dict with "source" (key column(s) on the table providing the inputs) and "target" (matching key column(s) on the table receiving the outputs). The result is merged by these keys, so the copied values can never disagree with the source table.	None

Example

CalculatedFeature.from_dict({ ... "calculated_features": "dsa.vat_value", ... "function": lambda fuel, shop: ((fuel + shop) * 0.2).round(2), ... "calculated_from": ["dsa.fuel_sales_value", "dsa.shop_sales_value"], ... })

Features are applied in the order they are declared; later features may consume the outputs of earlier ones.

apply_to(dataframe)

Apply self.function to dataframe.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	pandas.DataFrame. Dataframe to calculate the features on.	required

from_dict(data) staticmethod

Create a CalculatedFeature instance from a dict.

Parameters:

Name	Type	Description	Default
data	dict[str, str | Callable | list[str]]	dict.	required

Validation

ydata.synthesizers.multitable.calculated_features.validate_calculated_features_schema(table_columns, calculated_features, immutable_tables=None, protected_columns=None)

Validate calculated features against a SCHEMA (declared columns), not data.

Works for generation-from-nothing flows where the input columns may not exist as data yet. Features are validated in list order, and the outputs of earlier features count as available inputs for later ones (explicit chaining).

Parameters:

Name	Type	Description	Default
table_columns	dict[str, set[str] | list[str]]	declared columns per table.	required
calculated_features	list[CalculatedFeature]	features, applied (and validated) in list order.	required
immutable_tables	set[str] | None	tables (e.g. anchors) that features may read from but never write into.	None
protected_columns	dict[str, set[str]] | None	per-table columns (e.g. primary/foreign keys, scaffold dimensions) that features may read but never overwrite.	None

Raises:

Type	Description
SynthesizerValueError	on the first invalid feature found.

Application

ydata.synthesizers.multitable.calculated_features.apply_table_calculated_features(calculated_features, table, table_data, sample_tables)

Apply every calculated feature that outputs into table, in list order.

Intra-table features are computed directly from table_data's columns; cross-table features read their inputs from sample_tables and are merged in by their reference_keys. Features are applied in the order they were declared, so later features may consume the outputs of earlier ones.

Parameters:

Name	Type	Description	Default
calculated_features	list[CalculatedFeature]	all configured features (features targeting other tables are skipped).	required
table	str	name of the table being post-processed.	required
table_data	DataFrame	the table's synthesized data.	required
sample_tables	dict[str, DataFrame]	every table's synthesized data, for cross-table inputs.	required

Returns:

Type	Description
DataFrame	table_data with the calculated columns added.