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.