Number

Use Number for continuous scalar values: prices, counts, measurements, scores, datetime durations, and other numeric features.

{
  "amount": 42.75,
  "days_since_transaction": 3
}

import json2vec as jv

amount = jv.Number(
    "amount",
    jitter=0.02,
    objective="huber",
    p_mask=0.10,
)

amount

amount [number] active
 pooling=query weight=1 p_mask=0.1 p_prune=0 n_heads=4 n_linear=1
 jitter=0.02 n_bands=8 offset=4 objective=huber

Use Number only when numeric distance is meaningful. Numeric-looking labels such as zip codes, bounded product codes, and class labels are usually Category or Set. Large identifiers such as customer IDs, account IDs, and device IDs should usually stay as metadata or use Entity when local repeated equality is the useful signal.

Input Values

Number expects scalar numeric values. None is encoded as a null state, and missing branch positions are encoded as padded state. For repeated values, place the field inside a Branch.

Numeric content is normalized online by the embedder before Fourier features are computed, so models do not require pre-normalized inputs.

Date-derived numbers are appropriate when elapsed time is the signal. For example, compute days_since_transaction in preprocessing when risk depends on the difference between inference time and transaction time. The Device Tenure case study uses this pattern for account-risk histories.

Avoid raw timestamps unless absolute time is truly the intended signal. Raw timestamps can let the model memorize collection windows, rollout dates, policy changes, label leakage, or train/test split boundaries, and they may drift when future inference dates fall outside the training range.

Examples

Common number fields include:

• Monetary values such as amount, price, balance, or tax.
• Counts and quantities such as item count, attempts, clicks, or stock on hand.
• Measurements such as length, weight, intensity, duration, or distance.
• Scores and rates where numeric distance is meaningful.

Configuration

Option	Default	Notes
jitter	0.0	Adds training-time uniform noise after normalization to prevent overfitting. Must be >= 0.0.
n_bands	8	Advanced: negative exponent bound for log-spaced Fourier frequencies. Must be positive.
offset	4	Advanced: positive exponent bound for log-spaced Fourier frequencies. Must be positive.
alpha	None	Optional exponential update rate for the online normalizer. None uses cumulative statistics.
objective	"mae"	Content reconstruction objective: "mae", "mse", or "huber".

The total number of Fourier frequencies is n_bands + offset + 1.

Shared Preprocessing State

Number keeps normalization state on the field embedder: mean, variance, and count. During training, valued inputs update those statistics before the Fourier features are computed. During validation, test, and prediction, the learned normalization values are reused without updating them.

With alpha=None, updates are cumulative over observed training values. With an alpha value, the normalizer uses exponential moving updates. The normalization buffers are part of the model state and are used again after loading a checkpoint.

Target Behavior

When a Number is masked or used as a target, the decoder predicts:

• state: probabilities for valued, null, padded, and masked.
• content: a scalar numeric value.

The content loss is computed in normalized units, while tracked mae and rmse metrics are reported in the original value scale.

Prediction Output

Rendered examples use string paths for readability. The Python dictionary returned by Model.predict(...) is keyed by jv.Address objects.

Model.predict(...) returns a state probability map plus numeric content:

{
    "record/amount": {
        "state": {"valued": ..., "null": ..., "padded": ..., "masked": ...},
        "content": ...,
    }
}

{"record/amount": {"state": {"valued": "text/plain:Ellipsis", "null": "text/plain:Ellipsis", "padded": "text/plain:Ellipsis", "masked": "text/plain:Ellipsis"}, "content": "text/plain:Ellipsis"}}

Notes

Use Category for numeric-looking bounded labels or class labels. Keep massive identifiers out of the modeled schema unless you deliberately need a persistent global vocabulary. Number assumes the magnitude and distance between values are meaningful.

When a continuous scalar is not the right representation, binned numerical data or CDF-style transforms can be implemented with a custom data type or a preprocessor.