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.

Business rules

Pre-defined calculated features. Each member is a vectorised function, used as the function of a calculated feature. The full catalog — formulas and typical uses — is in the usage guide.

ydata.calculated.BusinessRule

Bases: str, Enum

Pre-defined business rules (calculated features) for finance and accounting.

Each member is the function itself — pass it as function in a calculated feature, with the input columns in calculated_from, in the order of the member's signature::

{"calculated_features": "vat_value",
 "function": BusinessRule.PRODUCT,
 "calculated_from": ["net_value", "vat_rate"]}

Fix a parameter to a constant by calling the member with it::

{"calculated_features": "gross_value",
 "function": BusinessRule.GROSS_UP(rate=0.23),
 "calculated_from": ["net_value"]}

Windowed members (CUMULATIVE_SUM, RUNNING_BALANCE, …) are applied per entity in order, so they need the synthesizer's partition and order columns (sequence in FakerSynthesizer, entities in the Metadata).

In a config file, the member's value can be used instead: "function": "product".

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. A pre-defined ydata.calculated.BusinessRule (e.g. BusinessRule.LINE_AMOUNT), or its name ("line_amount"), is accepted too; its input count is checked here, and a windowed rule is evaluated vectorised across partitions.	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.

calculated_from property

Input column(s), always as a list, in the order passed to function.

features property

Output column(s) this feature computes, always as a list.

function property

The callable that computes the outputs from calculated_from.

reference_keys property

Key pairs used to merge a cross-table feature.

Returns:

Type	Description
list[tuple[str]]	list[tuple[str]]: One (target, source) tuple per key column, where target is the key on the table receiving the outputs and source the matching key on the table providing the inputs. Empty for single-table features.

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, context=None) classmethod

Create a CalculatedFeature instance from a dict.

The dict is validated as a :class:CalculatedFeatureConfig.

Parameters:

Name	Type	Description	Default
data	dict[str, str | Callable | list[str]]	dict with calculated_features, function, calculated_from and optionally reference_keys, per_partition, window.	required
context	dict | None	what the synthesizer offers the feature, e.g. {"synthesizer": "RegularSynthesizer", "partition_by": []}.	None

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.