Skip to content

Arithmetic

Collections support +, -, *, /, //, ** and the comparisons, row by row and simulation by simulation. A Python scalar applies to every row and value.

net = gross * reserves.get_column(zk.FloatC[Lit["net_to_gross"]])  # one column each side
loaded = gross * 1.1 + 500.0  # a scalar broadcasts over every row and value

When two collections combine, their rows are lined up by the dimensions they share. Every row of one side must have a match on the other: see Combining collections.

One value column each side

Every operation between collections needs exactly one value column in each operand. Nothing broadcasts across value columns: with several on one side, which should pair with which?

with pytest.raises(ValueError, match="single value column"):
    reserves * 2.0  # three value columns: which should double?

doubled = reserves.get_column("gross_reserves") * 2.0

The error names the operation and the operand at fault:

ValueError: * needs a single value column in each operand, but the left operand has 3 columns ["premium", "gross_reserves", "net_to_gross"]; nothing broadcasts across value columns, so isolate one with get_column

get_column is the one way to pick a single column out. It keeps every dimension:

Method Returns
c.get_column("gross") or c.get_column(zk.FloatA["gross"]) A collection of just that value column, with all of c's dimensions. The type form also checks the column's type and types the result.
c.select_values(...), c.drop_values(...) A collection with a subset of the value columns.
c.rename({"gross": "net"}) The collection with value columns renamed.

A type checker enforces the same rule: a collection typed with several value columns, such as zk.Collection[Business, Premium, Gross] * 2.0, is flagged before you run it.

The result of an operation takes the name of its left operand's column.

Computing columns within a collection

To compute with several columns of one collection, use with_columns and zk.value(...), which refers to a value column by name, as zk.dim(...) refers to a dimension. Each expression is named by its keyword:

reserves = reserves.with_columns(
    net_reserves=zk.value("gross_reserves") * zk.value("net_to_gross"),
    loss_ratio=zk.value("gross_reserves") / zk.value("premium"),
).with_columns(net_loss_ratio=zk.value("net_reserves") / zk.value("premium"))

Each with_columns call reads the collection as it was before the call, so a column added in one call can be used in the next, as net_loss_ratio uses net_reserves.

A value expression supports +, -, *, / and //, the comparisons, and .clamp(lower, upper). It reduces across rows with .sum(), .mean(), .min(), .max() or .count(), in a group-by. For a jagged column, .jagged_sum(), .jagged_min(), .jagged_max() and .jagged_count() reduce each entry to one value first.

Simplification

zeki simplifies operations as it builds them, wherever an operand's value is known: a constant, or an input whose values are all the same. Dividing by a known value multiplies by its reciprocal (within one unit in the last place, and exact for a power of two), operations that do nothing (x + 0, x * 1) are dropped, and a layer (x - attachment).clamp(0, limit) runs as one operation. None of this changes what you write, only how fast it runs.