Skip to content

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:

shape = large.jagged_shape("large")
zeros = large.dim_rows.zeros(zk.FloatJ[Lit["large"]], jagged_shape=shape)
same_shape = large + zeros  # zeros that move with large, so they combine with it