Lengths¶
Two lengths are in play, and they have different names:
| Term | Of | Is | Read with |
|---|---|---|---|
| Row count | A collection | Its number of dimension rows | len(collection), collection.row_count |
| Length | A value cell | Its number of positions: an array's values, or a jagged value's entries | len(value), value.length; for a column, collection.value_length(name) or collection.value_lengths |
| Count | One entry of a jagged value | How many values the entry holds | jagged_count(), or the counts of a collected jagged column |
paid = zk.Collection(Business, Paid)
paid.add("motor", 2025, np.array([10.0, 20.0, 30.0]))
paid.add("motor", 2026, np.array([5.0, 15.0, 25.0]))
len(paid) # 2: the row count
paid.value_length("paid") # 3: each array's length
paid.value_lengths # [3]: one per column, None for a constant column
A constant has no length: len() of one raises TypeError, and its column's value_length is
None. Columns of one collection can have different lengths: there is no collection-wide length.
Arrays combine at equal lengths¶
Arrays combine only when their lengths are equal. Nothing is filled in implicitly. To combine a
shorter array with a longer one, pad it explicitly with the value expression pad_end(length,
fill=0), in with_columns:
later = zk.Collection(Business, Paid)
later.add("motor", 2025, np.array([1.0, 2.0, 3.0, 4.0, 5.0]))
later.add("motor", 2026, np.array([1.0, 1.0, 1.0, 1.0, 1.0]))
with pytest.raises(ValueError):
paid + later # lengths 3 and 5: nothing is filled in implicitly
padded = paid.with_columns(zk.value("paid").pad_end(later.value_length("paid")))
total = padded + later # paid's missing periods count as 0
The padded values stay tied to their inputs. A copula can't correlate cells that depend on inputs of different lengths, though, since one reordering can't apply to both.
Jagged values¶
A jagged value's length is its number of entries, usually one per simulation. That's where it lines
up with an array: an array of length n spreads over a jagged value of length n, entry by entry.
The jagged_ reductions reduce each entry to one value, giving an array of the same length:
def large_losses() -> tuple[np.ndarray, np.ndarray]:
counts = rng.poisson(0.5, 1_000) # how many large losses each simulation has
return counts, 250_000.0 * (1.0 + rng.pareto(2.5, counts.sum())) # one severity per loss
large = zk.Collection.of(Business, [("motor", 2025), ("property", 2025)]).with_columns(large=zk.float(large_losses))
large.value_length("large") # 1000: a jagged value's length is its number of entries
annual = large.jagged_sum("large") # an array per row: each simulation's total
largest = large.jagged_max("large") # each simulation's largest loss, 0 for none
count = large.jagged_count("large") # how many losses each simulation holds, as ints
An empty entry sums to 0, and its jagged_min and jagged_max are 0. Jagged values don't reduce
across rows until their entries have been reduced.
Arithmetic and clamp work value by value. A constant or a same-length array broadcasts over every
value, and two jagged values combine when their counts are bound to agree:
capped = large.clamp(0.0, 1_000_000.0) # value by value: each loss capped
retained = large - capped # jagged with jagged: the counts are bound to agree
excess = large - 500_000.0 # a constant broadcasts over every value
When counts agree¶
How many values each entry holds is part of what's lazy: a copula yet to be applied may move the entries. So two jagged values combine only if their counts are bound to agree, which zeki knows without evaluating anything: they start from the same counts, and have been reordered by the same copulas.
collection.jagged_shape(name) stands for a jagged column's counts without knowing them. For
example, dim_rows.zeros(...) makes zeros that move with the column, and so combine with it: