Data Types

A Branch groups related fields into a context. A tensorfield reads one kind of value, embeds it, and optionally learns to reconstruct it. Choose the type from the meaning of the value, not just its storage format.

Available Types

Meaning	Type
Continuous amount, count, age, or measurement	Number
Numeric position in a learned distribution	Quantile
True or false	Boolean
One learned label	Category
One label from a declared fixed set	Enum
Labels sharing learned latent groups	Cluster
Unordered label membership	Set
Related objects or repeated records	Branch
Recurring calendar position	DateParts
Identifier equality without a learned vocabulary	Hash
Supplied numeric vector	Vector
String meaning from a frozen encoder	Text

For example, a postal code is usually a Category, even when stored as an integer. A collection of product labels is a Set; products with quantities and prices belong in a Branch.

Category, Set, and Cluster learn labels through an online vocabulary. Its capacity, admission timing, and unknown values affect both training and prediction. Enum uses the labels declared in its schema and rejects values outside that set.

Value state

State describes a position; content carries its value. They are separate model inputs, so zero content does not have to mean null or padding.

State	Meaning
valued	A source value exists, including zero, false, empty strings, and empty sets.
null	The source explicitly contains null.
padded	The fixed schema geometry has no source position.
masked	An input has been replaced by a learned mask representation.
other	Reserved for extension-defined states; ordinary built-in inputs do not produce it.

One record can contain both empty and null sets:

items:
  - sku: mug
    tags: []
  - sku: plate
    tags: null

With a branch length greater than two, the unused item positions are padded. The first tags value is valued; the second is null. Structurally skipped inputs use separate presence information rather than a sixth state token.

An unknown Category is still valued; its categorical content is unavailable. Unknown Set members simply have no active vocabulary bit. Neither case is null. Keep one compatible Arrow value family per identity field: strings, binary values, integers, floats, and Booleans are distinct families. Number, Quantile, and Vector allow integer/float promotion. Datatypes own these contracts; custom tensorfields can declare their own.

Shared leaf options

The parent names a field with amount=rf.Number(...). Definitions have no name argument. Use a fields mapping for generated schemas or names that collide with configuration, and description for notes. Undeclared options are rejected.

Option	Default	Meaning
query	None	Read the parent’s same-named child; an explicit query selects another structural path.
description	None	Human-readable meaning or units.
active	True	Inactive leaves remain in the schema but do not encode, train, or predict.
nullable	True	Whether explicit nulls are allowed in the projected input.
mask	False	Visibility and reconstruction policies; see below.
weight	1.0	Positive multiplier on this field’s total loss.
embed	False	Export a normalized contextual embedding during prediction.
pooling	"query"	Decoder context pooling: "query" or "mean".
n_heads	4	Positive, even query-pooling head count; attention requires it to divide d_model with at least two dimensions per head.
dropout	None	Optional query-pooling dropout in [0, 1).
n_linear	1	Positive number of learned-query decoder pooling blocks.
decoder_position	None	Automatic: off for scalar targets, on for repeated targets. A Boolean overrides it.

These are the ordinary constructor defaults. Model size factories supply omitted decoder settings from their preset; explicit field options take precedence.

The common masking forms are:

• mask=False: visible input with no reconstruction policy.
• mask=0.15: train-only learned masking, without adding an objective.
• mask=True: always skip the input and reconstruct it as a supervised target.
• mask=rf.Mask(rate=0.15, reconstruct=True): sampled reconstruction.

A list or tuple combines explicit policies. A branch policy applies one decision to the corresponding descendant subtree. See Masking for query selection, skipping, and stage behavior. embed=True exports a representation; it does not create an objective.

What predictions contain

Decoded fields share state probabilities and a Boolean inferred flag. inferred marks requested reconstruction, not confidence. Each datatype owns its remaining payload:

Type	Decoded content
Number	Scalar in source units
Quantile	Scalar in source units; null before learning a distribution
Boolean	Probability of true
Category, Enum	Best label, probability, and optional candidates
Cluster	Best cluster and best vocabulary label, each with probability
Set	Label/probability pairs
Vector	Fixed-width reconstructed vector
DateParts, Hash, Text	No decoded public payload

All types can export an embedding when configured. Branches export context embeddings but never decode a typed branch value. See Embeddings for representation roles and Prediction output for Arrow shapes and access.