Model Builder

The ModelBuilder is the entry point for defining a model. Use its factory methods to add tables and named values, then call write_to_file() to emit the model definition JSON.

Related pages:

• Tables — the table types (data, derived, joined, union)

• Fields — fields that live on tables

• Named Values — calculations and parameters

• Formulas — the formula language and built-in functions

class ModelBuilder

Bases: object

Top-level entry point for building a Daitum model.

A model holds tables and named values (calculations and parameters). Build one incrementally with the add_* factory methods, then call write_to_file() to emit the JSON output.

__init__()

Initialise an empty model with no tables, calculations, or parameters.

add_calculation(id, formula, model_level=False, tracking_group=None)

Add a Calculation to the model.

Parameters:

• id (str) – Unique identifier for the calculation. Must not collide with any existing calculation or parameter id.

• formula (Operand | float | int | bool | str) – The expression. A Formula or any value accepted by CONST() (number, bool, or string), which is wrapped automatically.

• model_level (bool) – If True, the calculation is evaluated once for the whole model. If False (the default) it is scenario-level.

• tracking_group (str | None) – Optional change-tracking group. When set, a sibling *_TRACKING_* calculation is generated with references to other tracked named values and fields rewritten to their tracking ids.

Return type:

Calculation

Returns:

The newly added Calculation.

Raises:

ValueError – If a calculation or parameter with the same id already exists in the model.

add_parameter(id, data_type, value, model_level=False, tracking_group=None)

Add a Parameter to the model.

Parameters:

• id (str) – Unique identifier for the parameter.

• data_type (BaseDataType) – Data type of the parameter — a DataType, ObjectDataType, or MapDataType.

• value (Any) – Initial value. Must be compatible with data_type.

• model_level (bool) – If True, the parameter is shared across all scenarios. If False (the default) it is scenario-level.

• tracking_group (str | None) – Optional change-tracking group. When set, a sibling *_TRACKING_* parameter is generated with the same value.

Return type:

Parameter

Returns:

The newly added Parameter.

add_data_table(id)

Add a DataTable to the model.

A data table holds raw imported rows and is the only table type that supports decision variables.

Parameters:

id (str) – Unique identifier for the table. Must not collide with any existing table id.

Return type:

DataTable

Returns:

The newly added DataTable. Use its add_data_field / add_calculated_field / set_key_column methods to populate it.

Raises:

ValueError – If a table with the same id already exists.

add_derived_table(id, source_table, group_by=None, filter_field=None)

Add a DerivedTable to the model.

A derived table is a grouped, filtered, and/or sorted view of an existing source table.

Parameters:

• id (str) – Unique identifier for the derived table.

• source_table (Table) – The table whose rows the derived table draws from.

• group_by (list[Field] | None) – Optional fields to group rows by. When supplied, non-group fields must be added with an AggregationMethod.

• filter_field (Field | None) – Optional BOOLEAN field on source_table; only rows where it is True are kept.

Return type:

DerivedTable

Returns:

The newly added DerivedTable.

Raises:

ValueError – If a table with the same id already exists.

add_joined_table(id, join_conditions)

Add a JoinedTable to the model.

A joined table is the result of joining two or more tables on a list of JoinCondition rows.

Parameters:

• id (str) – Unique identifier for the joined table.

• join_conditions (list[JoinCondition]) – One condition per joined table pairing. The JoinType of each condition controls how unmatched rows are handled.

Return type:

JoinedTable

Returns:

The newly added JoinedTable.

Raises:

ValueError – If a table with the same id already exists.

add_union_table(id, source_tables)

Add a UnionTable to the model.

A union table stacks rows from multiple source tables. Pass a UnionSource instead of a bare Table when the source schema does not line up with the union table’s fields.

Parameters:

• id (str) – Unique identifier for the union table.

• source_tables (list[Table | UnionSource]) – The tables (or wrapped UnionSource instances) whose rows are stacked.

Return type:

UnionTable

Returns:

The newly added UnionTable.

Raises:

ValueError – If a table with the same id already exists.

set_partial_evaluation_allowed(partial_evaluation_allowed=True)

Toggle partial evaluation for this model.

When enabled (the default), the platform re-evaluates only the calculations affected by a change rather than the whole model, which speeds up UI rendering. Disable only if a model has dependencies that the partial evaluator cannot track correctly.

Parameters:

partial_evaluation_allowed (bool) – True to allow partial evaluation.

set_data_validation_rule(named_value)

Gate optimisation on a boolean named value.

Optimisation is allowed only while named_value evaluates to True. When it is False and the UI definition specifies a validation screen, the user is redirected there on attempting to start optimisation.

Parameters:

named_value (Parameter | Calculation) – A Parameter or Calculation of type BOOLEAN.

Raises:

ValueError – If named_value is not of boolean data type.

get_tables()

Return every table that has been added to the model, in insertion order.

Return type:

list[Table]

get_table(id)

Return the table with the given id.

Parameters:

id (str) – Identifier of the table to look up.

Return type:

Table

Returns:

The matching Table.

Raises:

ValueError – If no table with that id exists in the model.

get_named_value(id)

Return the named value (parameter or calculation) with the given id.

Parameters:

id (str) – Identifier of the named value to look up.

Return type:

Parameter | Calculation

Returns:

The matching Parameter or Calculation. Parameters are searched first, so a parameter is returned if both exist with the same id (which add_parameter / add_calculation would normally prevent).

Raises:

ValueError – If no named value with that id exists in the model.

get_validation_state()

Return (and lazily build) a calculation summarising current validity.

The calculation evaluates to the highest SEVERITY_RANK among every field, parameter, and calculation whose __invalid__ formula is currently True, or 0 when nothing is invalid. Useful as the gating value for set_data_validation_rule().

The result is registered in the model under the id __validation_state__. Subsequent calls return the already-registered calculation without rebuilding it, so call this only after every validator has been attached.

Return type:

Calculation | Parameter

Returns:

A model-level Calculation whose integer value is the highest severity rank of any currently-invalid entity.

write_to_file(model_directory)

Serialise the model into the canonical Daitum directory layout.

Writes three files under model_directory, creating it if it does not exist:

• model-definition.json — the full model definition from build().

• scenarios/Initial/named-values.json — scenario-level named values (those added with model_level=False).

• model-data/named-values.json — model-level named values (those added with model_level=True).

Parameters:

model_directory (str | PathLike[str]) – Destination directory. Parents are created as needed.

Return type:

None

build()

Build the JSON-compatible dict representation of the model.

On the first call, change-tracking metadata is resolved: tracked calculated fields have their formulas rewritten to reference the *_TRACKING_* ids of any other tracked named values and fields. This step is idempotent and only runs once per builder.

Return type:

dict[str, Any]

Returns:

A dict suitable for json.dump containing calculationDefinitions, parameterDefinitions, tableDefinitions, optimisationCheckNamedValue, and partialEvaluationAllowed keys.

to_named_value_dict(model_level)

Build the JSON-compatible dict of parameter values for one scope.

Parameters:

model_level (bool) – When True, include only model-level parameters (written to model-data/named-values.json). When False, include only scenario-level parameters (written to scenarios/Initial/named-values.json).

Return type:

dict[str, Any]

Returns:

{"values": {parameter_id: value_dict, ...}}.