pyhgf.updates.vectorised.categorical.vectorised_categorical_prediction#

pyhgf.updates.vectorised.categorical.vectorised_categorical_prediction(child_state, parent_state, weights, coupling_fn, parent_has_constant=False)[source]#

Predict a categorical state node layer: one belief per class.

The layer’s nodes jointly represent a single categorical choice. The incoming linear prediction plays the role of the logits, and the expected mean is their softmax across the layer:

\[\hat{\mu} = \mathrm{softmax}(W \, g(\hat{\mu}_{parent}))\]

All precision fields are set to one. This convention makes the layer compose with the existing kernels without special cases: with a one-hot observation clamped, the value prediction error is the raw residual one_hot - softmax(logits) (the cross-entropy gradient in logit space) the smoothing gain is exactly one (posterior precision equals the expected precision), so the message routed to the parent and the weight gradients coincide with the cross-entropy backpropagation quantities.

The softmax couples the nodes within the single categorical layer: each class’s expected mean depends on every class’s logit through the shared normalisation, so the nodes are not independently local. The layer acts as one joint unit. That unit is still local with respect to the rest of the network: it reads only its parent’s state and routes its residual back to that parent. No global normalisation or non-local dependency exists beyond the within-layer softmax.

Parameters:

  • child_state (LayerState) – Current state of the categorical child layer (being predicted).

  • parent_state (LayerState) – Current state of the parent layer (predictor).

  • weights (Array) – Weight matrix connecting child to parent, shape``(n_children, n_parents)`` or (n_children, n_parents + 1) when the parent layer includes a constant input node.

  • coupling_fn (Callable) – Coupling function applied to parent means.

  • parent_has_constant (bool) – If True, the parent layer has a constant input node (mean = 1.0) appended to its activations; the corresponding column of weights carries the bias connections and is treated as linearly coupled (\(g(1) = 1\)).

Returns:

Updated child layer state with the categorical expected values.

Return type:

LayerState