Quickstart

This guide walks through building a small daitum-model model end-to-end.

Installation

daitum-model is published on PyPI:

pip install daitum-model

To pin a specific version:

pip install daitum-model==1.0.0

It is also bundled in the daitum-core meta-package alongside daitum-ui and daitum-configuration — see the top-level Quickstart.

Source: github.com/daitumapi/daitum-core.

A minimal model

The ModelBuilder is the entry point. Build the model incrementally with its factory methods, then call write_to_file() to emit the JSON output:

from daitum_model import ModelBuilder, DataType
import daitum_model.formulas as formulas

model = ModelBuilder()

# A data table with three input fields.
products = model.add_data_table("Products")
products.set_key_column("ProductId")
products.add_data_field("ProductId", DataType.INTEGER)
price = products.add_data_field("Price", DataType.DECIMAL)
quantity = products.add_data_field("Quantity", DataType.INTEGER)

# A calculated field. Formulas compose with Python operators or via
# daitum_model.formulas helpers.
products.add_calculated_field("TotalValue", price * quantity)

# A model-level parameter and a model-level calculation.
model.add_parameter("TaxRate", DataType.DECIMAL, 0.15, model_level=True)
model.add_calculation(
    "TotalRevenue",
    formulas.SUM(products["TotalValue"]),
    model_level=True,
)

# Emit model-definition.json and the scenarios/named-values JSON files.
model.write_to_file("output")

The objects returned by add_data_field and friends are Field instances that can be used directly in formula expressions, as shown by price * quantity. products["TotalValue"] returns a Formula that references the named field.

Grouping with a derived table

A DerivedTable produces a grouped view over a source table. Aggregated fields are added with an AggregationMethod:

from daitum_model import AggregationMethod

products.add_data_field("Category", DataType.STRING)
category = products.field_definitions["Category"]

summary = model.add_derived_table(
    "ProductsByCategory",
    source_table=products,
    group_by=[category],
)
summary.add_source_fields([category])
summary.add_aggregated_field("TotalQuantity", quantity, AggregationMethod.SUM)
summary.add_aggregated_field("AveragePrice", price, AggregationMethod.AVERAGE)

Where to next