AtSubscripts¶
Apply subsampling (if any) imposed by enclosing With Stacked Variables nodes (plates) to the given data.
This node is mainly for use in conjunction with plates that apply subsampling along their axis of interest (i.e., have their subsample option set). This is for use with "mini-batch" style stochastic inference, but can also be used to express that data is conceptually subscripted by the plate's index, even if the plate may not have subscripting enabled. The node will automatically detect the enclosing plate context(s), provided that it is situated inside the context as per NeuroPype's usual rules - that is, the node must be situated downstream of the plate subscript placeholder (this is often done with just an update-update edge from the Placeholder to the At Subscripts node). In case of nested plates, it is generally sufficient to connect only the innermost plate's subscript placeholder to the At Subscripts node since the entire context is nested within the outer plates (also note you can always check that the node is properly situated by (shift+)ctrl-clicking on the dotted edge going into the plate node in question). As long as the axes referenced by the enclosing plates are uniquely identified within the data (e.g., the data has no duplicate axes unless they have distinct labels), the operation is guaranteed to apply correctly. The node can be used with plain array data, but this considerably more difficult to configure: the event-space dimensionality must be set correctly (matching that of the distribution used by the Random Draw node that the data is subsequently wired into as an observation), and the axes must be in the positions (relative to event-space dimensions) expected by the enclosing plates, which can mean that the stacking dimension of those plates also needs to be set in accordance with the data. For these reasons it is recommended to use named axes (e.g., a Packet) when possible. The node also has limited support for partial mixing of data with axes passed into random draws that generate plain arrays: if the event-space dimensionality is set correctly, the node will reorder the axes to the positions expected by the plates and random draws, so that the user only needs to get the random draws and distribution parameters right. More Info... Version 1.0.0
Ports/Properties¶
data¶
Data to subscript.
- verbose name: Data
- default value: None
- port type: DataPort
- value type: AnyNumeric (can be None)
- data direction: INOUT
num_event_space_dims¶
When applying to plain array data, this is the number of event-space dimensions in the data. This setting is not needed in the common case where the statistical model is set up to use named axes in both the data and any Random Draw nodes that the data will come in contact with.
The number determines how many dimensions to the right of the data's array shape are set aside as event-space dimensions that are intrinsic to the distribution on hand (e.g., discrete class labels or dimensions of a multivariate distribution), while the rest are considered "batch" dimensions, to which plate subscripts are applied. When the data is a plain array or when the resulting data gets in contact with parts of the statistical model that use plain arrays (namely the random draws and their distributions that the result subscripted data should interact with), this must be set (the only case where this is inferred for plain arrays is when the plates necessarily bind all axes in the array, leaving 0 as the only possible number of event-space dimensions).
- verbose name: Event-Space Dimensionality
- default value: None
- port type: IntPort
- value type: int (can be None)
on_missing_axes¶
How to handle the case where a block or packet is lacking an axis that an enclosing plate context applies to. If set to 'insert', a dummy axis will be inserted into the block or packet to match the plate's expectations; this is most likely what the user wanted, since it ensures that the resulting data will broadcast correctly with other data that has been subscripted by the same plates. The option 'insert (as needed)' is the same but will not prepend any dummy axes; this will still broadcast correctly with other data but results in a "cleaner-looking" array shape. The default is set to 'warn and insert' not because it is generally safer, but because the operation may otherwise silently hide genuine errors where the user accidentally had mismatching axes between plates and the data. Setting this to 'error' can help catch cases where invalid data is somehow making its way into a model that has been set up to not generate these errors, for example in a complex pipeline or a model being used in multiple places.
- verbose name: On Missing Axes
- default value: warn and insert
- port type: EnumPort
- value type: str (can be None)
on_ambiguous_axes¶
How to handle the case where a block or packet has an axis referenced by a plate that may be ambiguous (where the plate matches two or more axes in the data). Note that this is only a best practice and the check can have false positives that behave as the user intended: for example, two plates each referencing the same axis will resolve such that the outermost plate will bind the first axis of the type in the data and the next plate will bind the second axis of the type, which can be as intended. Another case is two axes that are entirely interchangeable as long as the operation applies to both of them, like in a covariance matrix. A third case is where one plate binds an axis ambiguously but there is at least one other plate and once those are accounted for, the remaining ambiguity is resolved since there is only one axis that could be matched. The message will reflect the likely degree of ambiguity. The user may set the option to 'ignore' to suppress the warning. The 'warn' option will emit a warning each time the node is executed, while 'warn-once' will emit a one-time warning during the session. The 'error' option will raise a ValueError exception. Ignore will suppress the warning.
- verbose name: On Ambiguous Axes
- default value: warn
- port type: EnumPort
- value type: str (can be None)
set_breakpoint¶
Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.
- verbose name: Set Breakpoint (Debug Only)
- default value: False
- port type: BoolPort
- value type: bool (can be None)
metadata¶
User-definable meta-data associated with the node. Usually reserved for technical purposes.
- verbose name: Metadata
- default value: {}
- port type: DictPort
- value type: dict (can be None)