← bayesian package

RandomDraw

Draw a random sample from a distribution, resulting in a random variable.

This node is used to realize a random variable in a statistical model. The role of this node is that a statistical model prescribes a generative process (a randomized "simulation") that characterizes how some data may have been generated, and this is modeled as a series of random draws from specific distributions, which can be chained, hierarchical, or depend on unmodeled observed data (sometimes called "independent" variables). So-called "dependent" variables in the data (data that is explained by the model) are wired as a side input into the 'observation' port of the respective Random Draw node that is meant to model them. The resulting overall model characterizes a "prior" distribution over both the latent random variables and the (observable) dependent variables, and which is optionally parameterized by the independent variables (these are supplied from Placeholder nodes inside the model). An Inference node, when given a model and invoked with some data (via its own 'data' port), passes any independent variables through the model, and propagates information from the dependent variables back through the model to infer the most likely "posterior" distribution over latent variables given the observed data. The model, once a posterior has been inferred, can also be used to generate posterior predictions for any of the dependent variables (posterior predictive distribution) given new values for independent variables. The inference node will do this automatically whenever it is given new data to predict on. Random variables are generally named (see the "variable name" setting of this node), and the random draw itself is done according to a distribution, which can either be specified in the node (via the "distribution" setting) or instead one of the Distribution nodes (in the distributions package) can be wired into the "dist" input port of this node. The latter allows one to create dependencies between random variables, by using the output of one draw, wiring it into a parameter of a Distribution node, and then wiring that distribution into another Random Draw node. The node also offers limited support for reparameterization "tricks" via the reparameterize option; which by default will apply decentering in the most common cases. Besides the optional observation input, a random draw can take in additional side information: this includes an optional mask array (which can be used to mask out certain values in the observation, which are then imputed during inference), and an optional weight array: the weight behaves similarly to the 'sample weight' in a machine learning context and can be used to account for class imbalance or other applicable data weightings. In many cases, a Random Draw will yield multivariate data, and in such cases it is important that unique axes (or customs labels, if an array has multiple of the same axis) are used for different dimensions as needed to avoid ambiguities. Axes can occur in either the like input (which can be used to match the axes of some other data) or by using a distribution that was itself constructed from parameters that had axes. One may also use the shape input, but this is less commonly done (see notes in the setting); with these provisions, axes typically flow forward from the input data through the model and can be managed like in any other NeuroPype pipeline. I It is also possible to imbue random draws with additional non-singeton axes using a With Stacked Variables context (see node for more details), which is simlar to Bayesian plate notation. By default, random draws used in conjunction with inference will use 'matched' axis pairing, which guarantees that all operands from any source will have their axes mutually lined up by type and optionally by axis label. In this context, the output axis order will be dictated by the like input (if given), otherwise by applicable plates (With Stacked Variable contexts, if present) and otherwise will follow from a combination of the distribution, and the shape setting (if given). The observation, mask, and weight axes do not control the order of the output axes but will be reordered to match the node. When the node is used with only plain arrays or undifferentiated axes, great care must consequently be taken to line up positions of dimensions between the various inputs of the node, the distributions, and the applicable plate contexts, which can be exceedingly difficult for large models; therefore this is not recommended. Also note that, unlike other neuropype nodes, each random draw yields only a single array and a distribution only specifies a single array, and therefore the like input, if given as a packet, may only contain no more than one stream. More Info... Version 1.0.1

Ports/Properties

sample

The generated sample.

• verbose name: Sample
• default value: None
• port type: DataPort
• value type: AnyNumeric (can be None)
• data direction: OUT

dist

Optionally a distribution to sample from.

• verbose name: Dist
• default value: None
• port type: DataPort
• value type: Distribution (can be None)
• data direction: IN

observation

Optional observed value for this variable. Information provided by concrete observations is propagated at inference time to deduce the most likely distribution of all variables in a given statistical model. This can be used as side information to help the inference engine infer the answer to, roughly, "what is the most likely shape of distributions if we observed this value at this site?" Must have a shape compatible with what is specified via the shape parameter, but is not limited to arrays (e.g., can be a Packet).

• verbose name: Observation
• default value: None
• port type: DataPort
• value type: AnyNumeric (can be None)
• data direction: IN

mask

Optional mask that can be used to mask out certain values in the observation. The masked values may then be imputed (estimated) during inference. Note that, if the underlying distribution has a non-trivial event space, the mask will not include the event space axes.

• verbose name: Mask
• default value: None
• port type: DataPort
• value type: AnyNumeric (can be None)
• data direction: IN

weight

Optional weight for the random draw. Note that, if the underlying distribution has a non-trivial event space, the weight will not include the event space axes.

• verbose name: Weight
• default value: None
• port type: DataPort
• value type: AnyNumeric (can be None)
• data direction: IN

seed

Optional random seed to force a fixed result. Must have been created with one of the RandomSeed nodes. Unlike other Random nodes, this node is normally NOT used with a fixed seed since it will receive one from the context within which it is used (e.g., one of the Inference nodes).

• verbose name: Seed
• default value: None
• port type: DataPort
• value type: AnyArray (can be None)
• data direction: IN

like

Optional object (e.g ., Packet, Block, or array) whose shape and data format to adopt when generating the sample.

• verbose name: Like
• default value: None
• port type: DataPort
• value type: AnyNumeric (can be None)
• data direction: IN

varname

Name of the resulting random variable. The variable can be accessed under this name when working with derived distributions such as the posterior distribution for a given model. Note that, if a packet is wired into the like input, the stream name in that packet will be suffixed onto the variable name with an underscore separator (e.g., 'myvariable_eeg').

• verbose name: Random Variable Name
• default value: myvariable
• port type: StringPort
• value type: str (can be None)

distribution

Optionally a distribution name from which to draw the variable. If a distribution is provided via the dist input, this must be left at the default value 'provided'. You can name of any of NeuroPype's Distribution nodes here (without the "Distribution" suffix), and parameters can be specified positionally in the same order as defined in the node; remaining parameters retain their defaults (see drop-down for examples).

• verbose name: Distribution
• default value: provided
• port type: ComboPort
• value type: str (can be None)

shape

Shape of the sample to draw. Can be a list of integers or axes. Note that if the distribution has a multivariate "event space" (e.g., a multivariate normal or some discrete distributions) then the sample shape concatenates to the left onto the dimensionality of that event space. Note that A more commonly used scenario is instead to wire an object into the like input, whose shape (and data type, i.e. array, chunk, block, or packet) will then be matched by the generated data of the random draw.

• verbose name: Sample Shape
• default value: []
• port type: ListPort
• value type: list (can be None)

reparameterize

Whether and how to reparameterize the variable. This can be used to improve the convergence of the inference algorithm, for example to avoid funnel geometries (see Neal's funnel). Several inference algorithms will work better if variables have mean zero and unit standard deviation, and this can be achieved by running the algorithm on a transformed version of the variable and automatically back-transforming the result afterwards. The following options are available: decenter enables location/scale decentering, which is the most common reparameterization. The minimal option will by default apply reparameterization for a select few distributions that would otherwise lead to an error, specifically the VonMises and ProjectedNormal distributions. Note this option will NOT automatically detect when to perform decentering for any other distributions. The heuristic option will select either minimal or decenter based on a heuristic that aims to determine whether decentering is applicable (currently, a variable is automatically decentered if a distribution is wired in, that distribution has both a location and scale parameter (and optionally other shape parameters), and has unbounded support, and the location or scale are driven by other random variables); note this heuristic may be refined in subsequent NeuroPype versions. The remaining options are specific to certain distributions: transformed dist. can be used if the distribution was an instance of a transformed distribution, projected normal. dist. can be used if the distribution is of projected-normal type, and circular dist. can be used if the distribution is circular (i.e., von mises). The variationally inferred decentering is not exposed in NeuroPype 2025 and behaves like fixed decentering, but this may change in future versions.

• verbose name: Reparameterize
• default value: heuristic
• port type: EnumPort
• value type: str (can be None)

desc

Description text for the variable. This can be used to annotate the purpose/meaning of the variable in the context of a statistical model. This is often a single sentence.

• verbose name: Description
• default value:
• port type: StringPort
• value type: str (can be None)

verbose_name

Optional verbose name for the variable. Can be used for augmented human-readable output.

• verbose name: Verbose Name
• default value: None
• port type: StringPort
• value type: str (can be None)

axis_pairing

How to pair axes of the inputs. In 'positional' mode, axes are paired by their position according to a right alignment, that is, the last axis of the first operand is paired with the last axis of the second operand, and so on, while any missing axes behave as if they were unnamed axes of length 1 (this is the same way plain n-dimensional arrays pair in Python/numpy). In 'matched' mode, axes are paired by their type and optionally label, where the axis order of the first operand is preserved in the output, optionally with additional axes that only occur in the second operand prepended on the left. The other operand then has its axes reordered to match. All axis classes are treated as distinct, except for the plain axis, which is treated as a wildcard axis that can pair with any other axis. See also the 'label_handling' property for how labels are treated in this mode. The 'default' value resolves to a value that may be overridden in special contexts (mainly the ambient Inference node) and otherwise resolves to the setting of the configuration variable default_axis_pairing, which is set to 'positional' in 2024.x. Note that axis pairing can be subtle, and it is recommended to not blindly trust that the default behavior is always what the user intended.

• verbose name: Axis Pairing
• default value: default
• port type: EnumPort
• value type: str (can be None)

label_pairing

How to treat axis labels when pairing axes in 'matched' mode. In 'always' mode, labels are always considered significant, and axes with different labels are always considered distinct, which means that, if the two operands each have an axis of same type but with different labels, each operand will have a singleton axis inserted to pair with the respective axis in the other operand. In 'ignore' mode, labels are entirely ignored when pairing axes; this means that, if multiple axes of the same type occur in one or more operands, the last space axis in the first operand is paired with the last space axis in the second operand, etc. as in positional mode. In 'auto' mode, labels are only considered significant if they are necessary for distinguishing two or more axes of the same type in any of the operands, or if they occur on a plain axis.

• verbose name: Label Pairing
• default value: auto
• 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)