Skip to content

Reading values out

Collect a collection to read its values: collection.collect() for one, or zk.collect_all(...) for several in one pass (see Lazy and eager). The examples on this page read this small collection:

Premium = zk.FloatC[Lit["premium"]]
Gross = zk.FloatA[Lit["gross"]]
Large = zk.FloatJ[Lit["large"]]

book = zk.Collection(Business, Premium, Gross, Large)
book.add("motor", 2020, 100.0, np.array([1.0, 2.0]), (np.array([2, 0]), np.array([5.0, 6.0])))
book.add("property", 2020, 50.0, np.array([3.0, 4.0]), (np.array([0, 1]), np.array([7.0])))

Plain Python: to_list

to_list() gives one (dim_row, value_row) pair per row, in row order. dim_row maps each dimension's name to the row's value, and value_row maps each column's name to its value cell: the value itself for a constant column, a list for an array column, and a list of lists, one per entry, for a jagged column.

values = book.collect()
values.to_list()
# [({"class_of_business": "motor", "underwriting_year": 2020},
#   {"premium": 100.0, "gross": [1.0, 2.0], "large": [[5.0, 6.0], []]}),
#  ({"class_of_business": "property", "underwriting_year": 2020},
#   {"premium": 50.0, "gross": [3.0, 4.0], "large": [[], [7.0]]})]

NumPy: to_numpy

to_numpy(name) gives one column as NumPy:

Column Gives
Constant A (rows,) array
Array A (rows, length) array
Jagged A (counts, values) pair: counts is a (rows, length) int array of how many values each entry holds, and values holds every value, row after row and entry after entry
values.to_numpy("premium")  # array([100., 50.]): one per row
values.to_numpy("gross")  # a (rows, length) array: [[1., 2.], [3., 4.]]
counts, losses = values.to_numpy("large")  # counts [[2, 0], [0, 1]], losses [5., 6., 7.]

Polars and pandas

to_polars() gives a Polars DataFrame with a row per row: a column per dimension, then a column per value column. A constant column has its kind's own dtype, an array column is a pl.Array, and a jagged column is a pl.Array of pl.Lists. A dimension and a value column with the same name raise a ValueError: rename one of them first.

to_pandas() gives a single constant or array column as a pandas Series or DataFrame, indexed by dimension row. A jagged column has no pandas form: read it with to_polars().

frame = values.to_polars()  # a column per dim, then per value column
gross_frame = gross_values.to_pandas()  # one column: a (rows x length) DataFrame, indexed by dim row

One cell at a time

get_constant, get_array and get_jagged read one cell, by dimension row and column name. They give a Python value, a (length,) NumPy array, or a (counts, values) pair:

values.get_constant(("motor", 2020), "premium")  # 100.0
values.get_array(("motor", 2020), "gross")  # array([1., 2.])
values.get_jagged(("property", 2020), "large")  # (array([0, 1]), array([7.]))

A collection with no dimensions has one dimension row, (), and reads the same way:

book.get_column("gross").sum().collect().to_list()
# [({}, {"gross": [4.0, 6.0]})]

A dimension row or column the collection doesn't have, or a column of another shape, raises a ValueError.

Cells of a lazy collection

On a Collection itself, the same get_constant, get_array and get_jagged read one cell lazily. It comes back as a value of the column's type, such as zk.FloatA["gross"], which keeps its place in the model's lineage, so it stays tied to everything it was built from. add takes one back into another collection:

cell = book.get_array(("motor", 2020), "gross")  # FloatA['gross'](length=2), still lazy
other = zk.Collection(Business, Gross)
other.add("motor", 2021, cell * 2.0)  # stays tied to everything cell was built from

A type checker matches the name against the collection's column types, so a cell read this way is typed zk.FloatA[Literal["gross"]].