Number

Use Number for a scalar whose magnitude matters: an amount, quantity, age, or measurement. Use Category for numeric-looking labels and DateParts for recurring calendar positions.

amount: 42.75
age_days: 3
returned: false

import relflow as rf

model = rf.Model(
    d_model=64, n_layers=2, n_heads=4,
    amount=rf.Number(jitter=rf.Jitter(add=0.02)),
    age_days=rf.Number,
    returned=rf.Boolean(mask=True),
)

Input and representation

The Arrow leaf must contain integers or floating-point values. Put repeated measurements inside a Branch. Nulls and absent branch slots have separate value states.

The embedder standardizes values using learned online statistics, then combines Fourier features with a scalar signal. Very large or non-finite normalized values are clamped for Fourier safety; this is not application-level range validation. Normalize units and reject invalid measurements upstream.

Options

Option	Default	Meaning
jitter	rf.Jitter()	Training noise; normalize=True uses standardized units, False uses source units. See Jitter.
n_bands	8	Positive lower Fourier exponent bound; frequencies start at 2 ** -n_bands.
offset	4	Positive upper Fourier exponent bound; frequencies end at 2 ** offset.
alpha	None	Cumulative normalization; a value strictly between 0 and 1 selects exponential updates.
objective	"mae"	Reconstruction loss: "mae", "mse", or "huber".

There are n_bands + offset + 1 Fourier frequencies. Shared leaf options control masking, decoder pooling, and exported embeddings.

Learned state and output

Normalization observes finite, valued pristine training values, before masking and jitter. Validation, test, and prediction reuse these statistics; checkpoints preserve them. Distributed training combines each batch’s sufficient statistics across ranks before updating.

For an application-supplied trained model:

normalization = rf.Number.normalization(model, "record/amount")

The snapshot contains mean, variance, std, count, and alpha. Repeated training presentations count again; count is None for exponential updates.

Reconstruction loss scales errors by the learned standard deviation. MAE and RMSE metrics use source units. Prediction content is a float64 scalar, even when the most likely predicted state is not valued; read it alongside state and inferred in the prediction envelope.

The null-versus-zero proof isolates the information in validity state. The weighted-sum proof tests learned interaction between visible numeric fields, with controls for their pairing and order.