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:
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"]].