Category

Use Category for one label from a learned vocabulary: a country, product family, customer tier, or class. Use Set for multiple labels, Hash for identifier equality, and Text for word meaning. Use Enum when the schema declares every allowed label in advance.

merchant_category: grocery
fraud: false

import relflow as rf

model = rf.Model.sm(
    merchant_category=rf.Category(topk=[3, 10]),
    fraud=rf.Boolean(mask=True),
)

Input and options

Accepts scalar Boolean, integer, floating-point, string, or binary labels. Keep one compatible Arrow type family per field; normalize inconsistent labels upstream. A null is a value state, not a vocabulary member.

Option	Default	Meaning
p_unavailable	0.01	Training probability of replacing known valued input content with unavailable content. Reconstruction targets are unchanged.
topk	[]	Sorted, unique integer accuracy cutoffs greater than one; also controls prediction candidates. Each cutoff is capped by the discovered label count at runtime.

Vocabulary storage grows automatically; there is no size option to configure. See shared leaf options for reconstruction and embedding configuration.

Vocabulary and learning

Pristine training observations add labels before forward, growing storage as needed. The training process resolves batch-local dictionaries from encoding workers and gathers labels across DDP ranks. Validation, test, and prediction reuse the frozen mapping; checkpoints preserve it and the grown tables.

See Online Vocabulary for admission order, growth and state preservation, supported training strategies, and reuse during fine-tuning.

An unknown label stays valued but contributes zero categorical content to the encoder. Its internal sentinel is not an extra embedding row or decoder class. Known labels contribute learned content plus their state embedding.

Reconstruction uses unweighted state and categorical cross entropy. Class frequencies remain observable through counts, but do not silently change the probability objective. Training scores only discovered labels; spare storage does not contribute classes or gradients. Unavailable valued targets have no categorical loss or gradient: an unknown answer does not imply a uniform distribution over known answers. State supervision is retained.

For each reconstruction objective, epoch metrics separate coverage from quality:

Metric suffix	Meaning
targets.known, targets.unavailable	Counts of selected valued targets inside and outside the vocabulary.
coverage.content	Known targets divided by all selected valued targets.
accuracy.content, accuracy.topK	Correct predictions among known targets, using populated candidates.
accuracy.all	Correct predictions divided by all selected valued targets; unavailable answers count as wrong.
nll.content	Unweighted negative log likelihood over populated candidates, matching written probabilities.
loss.content	Unweighted categorical training objective over populated labels, averaged over known targets; equal to nll.content.

Names include the field address and stage, for example .merchant_category/validate.coverage.content. Counts and sums aggregate across batches and ranks before division. With no known targets, conditional accuracy, NLL, and content loss are NaN, not zero; coverage and all-target accuracy are zero when selected valued targets exist. With no selected valued targets, coverage and all-target accuracy are also undefined.

For an application-supplied trained model:

labels = rf.Category.vocabulary(model, rf.Address("merchant_category"))
counts = rf.Category.counts(model, rf.Address("merchant_category"))

vocabulary returns a tuple snapshot in index order; counts returns pristine valued training exposures, excluding nulls, unavailable values, unused slots, and the smoothing prior. Repeated epochs count again; DDP counts synchronize at epoch end. vocabulary also accepts a preprocessor’s encoding_context. Consult it for inference preprocessing only: training preprocessing occurs before new labels are reserved.

Prediction

content contains value, probability, and topk. The candidate list has up to max(topk) entries, capped by the populated vocabulary; it is empty when no cutoffs are configured. Labels are written as large_string.

Probabilities are renormalized over populated labels, excluding unused capacity and the unavailable sentinel. An empty vocabulary yields a null best label and probability zero. Confidence is not an unknown-label detector. With only one populated label, its conditional probability is one even before learning; vocabulary membership is not evidence of predictive competence. Unweighted cross entropy removes a systematic class-weighting distortion, but does not guarantee calibration under finite data or distribution shift. See the prediction envelope for shared state probabilities, inferred, and repeated shapes.