Skip to content

Schemas

Dimensions

Dims

Base class for a set of dimensions. Subclass it with Dim attributes. The class iterates over its dims in order: for dim in ReserveDims.

dims classmethod

dims() -> list[Dim]

The declared dims, in order.

NoDims

Bases: Dims

The dims of a collection reduced across every row, such as collection.sum(): there are none, and the collection has a single row. Combining it with a collection of other dims broadcasts its values to every one of their rows.

Dim

Dim(name: str, kind: type[str] | type[int] | type[float])

A named axis whose dim cells are str, int or float. Two dims are equal when their names and kinds are, however they were created.

A float dim holds numbers that tell rows apart and that values are computed from - the parameters each row is sampled with, say, which zk.float passes a function. Its dim cells are never NaN, and -0.0 is 0.0.

Dim(kind) declares a dim in a Dims class body, which names it after its attribute; it can't be used in a collection until then.

name property

name: str

The dim's name. Raises ValueError for an unnamed Dim(kind).

Value columns

ValueColumns

Base class for a set of value columns. Subclass it with ValueColumn attributes. The class iterates over its columns in order: for column in Reserves.

columns classmethod

columns() -> list[ValueColumn]

The declared value columns, in order.

ValueColumn

ValueColumn(
    name_or_type: str | type[Value],
    value_type: type[Value] | None = None,
)

A value column: a name and a type such as FloatA. ValueColumn(type) declares one in a ValueColumns class body, which names it after its attribute. Value columns are equal when their names and types are.

has_name property

has_name: bool

False for a ValueColumn(type) that hasn't been named by a ValueColumns class yet.

type property

type: type[Value]

The column's type, such as FloatA.

kind property

kind: type

The Python type of the column's values: float, int, bool, datetime.date or str.

shape property

shape: str

"constant", "array" or "jagged".

Value

Value()

Bases: ValueColumns

A Value: what one value cell holds - a constant, an array or a jagged value. Every column type (FloatA and so on) subclasses it. A type is passed to ValueColumn to declare a column of it; subscripting one with a column name gives a ValueColumns class declaring that one column, cached so the same name always gives the same class.

An instance is one value cell of a column of the type, as collection.get_constant, get_array and get_jagged read it: the cell's node in the lineage, so it stays tied to everything it was built with, and Collection.add takes it back into a column of its kind and shape.

Values combine as columns do, with Values of their kind and with Python scalars: + - * / //, the comparisons < <= > >= == !=, and zk.min/zk.max. Shapes broadcast as for columns - a constant over an array or jagged value, and an array over a jagged value of its length, entry by entry - and the result is named after the left operand, unless it's the scalar. A comparison gives a bool Value, as Polars' expressions do, so a Value has no truth value and isn't hashable. Each class's operators are written by tools/generate_overloads.py.

length property

length: int

The Value's length, as len(value): an array's number of values, or a jagged value's number of entries - its outer length, so an array and a jagged value of one length line up entry by entry. (How many values each entry holds is its count.) A constant has no length: TypeError.

Value types

Every value type pairs a kind with a shape. Subscript one with a name to declare a column: zk.FloatA[Literal["gross"]]. See Value types.

Kind Constant Array Jagged
float FloatC FloatA FloatJ
int IntC IntA IntJ
bool BoolC BoolA BoolJ
datetime.date DateC DateA DateJ
str StringC StringA StringJ

FloatC

FloatC()

Bases: Value, Generic[ColumnName]

One float per cell: zk.Collection[SomeDims, zk.FloatC[Literal["premium"]]].

FloatA

FloatA()

Bases: Value, Generic[ColumnName]

An array of floats per cell, as FloatA[Literal["name"]].

FloatJ

FloatJ()

Bases: Value, Generic[ColumnName]

A jagged value of floats per cell, as FloatJ[Literal["name"]].