← bayesian package

MCMCInference

Apply Bayesian inference given data and a wired-in statistical model, using a Markov Chain Monte-Carlo (MCMC) approach.

This is the most reliable and flexible of the inference nodes and should be the starting point of most Bayesian analyses. Like the other Inference nodes, this node "updates" a prior distribution (as formalized by a statistical model) given observed data, yielding a (joint) posterior distribution over the latent (unobserved) variables in the model. The posterior can be accessed for further analysis via the samples output ports The node prints basic diagnostics and suggestions by default, but note that the main diagnostics require multiple chains to be configured. Once a posterior has been inferred, the node can also be used for predictve inference of dependent variables when new data is passed in, and these predictions are available over the data output port, so the node can be used as a drop-in replacement for other machine-learning node in NeuroPype; the inference result can also be saved and loaded back in via the model port. The statistical model is the portion of the graph that is wired into the "graph" input port and runs under the control of the node; see the "Graph [signature]" documentation (tooltip) for more detail on how statistical models can be built using nodes such as Random Draw or With Stacked Variables. Also like the other inference nodes, the resulting distribution is represented by a collection of samples whose distribution matches that of the posterior; these can be scatter-plotted, summarized via moment or quantile statistics, or propagated through downstream computations. The MCMC node is quite robust and efficient and requires little tuning when used with the default "NUTS" sampler option (sampler type parameter). The sampler type may have to be changed if your model contains discrete latent variables (e.g., is a mixture model), or if you have robustness issues (e.g., nan's). Other tuning knobs are the posterior correlations parameter, the number of warmup and posterior samples to generate, and the init strategy. You can also retrieve the convergence history to find out how well or how quickly your inference is converging via the history output port. For most uses it is recommended to set the number of chains greater than the default of 1 (e.g., 4), which enables better diagnostics. One can also wire in a separate Sampler node for more control over options of the sampler and more comprehensive documentation. Other remedies for convergence issues are close inspection of the model for signs of mis-specification such as non-identifiable variables, funnel geometries (Neal's funnel), or variables that can use reparameterization (see option in the Random Draw node), or using more benign distributions or generally starting with a simpler model. The node supports two alternative sampling engines (numpyro and blackjax) of which the former is more comprehensively tested and thus preferred, but one may experiment with falling back to blackjax if issues with numpyro are suspected (e.g., crashes, GPU hangs, or etc). Like other GPU-compatible ML nodes in NeuroPype, the wired-in input data is slightly reorganized for more efficient compute, and among others, the instance axis of your data will appear as a separate stream with a feature axis (indexing the instance-axis fields such as the TargetValue) and a (blank) dummy instance axis indexing the instances. This can be further configured via options in the "Input" category. More Info... Version 1.0.0

Ports/Properties

data

The data to process.

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

samples

Generated posterior samples in the desired format.

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

history

History trace of inference process.

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

graph

The graphical model to use.

• verbose name: Graph
• default value: None
• port type: GraphPort
• value type: Graph

graph__signature

Argument names accepted by the wired-in graphical model (statistical model). This is a listing of the names of input arguments of your statistical model, which is typically a single argument conventionally named "data" (although you can choose your own name) followed by a catch-all tilde symbol, as in (data,~). This data argument then receives the same data given to the inference node (via its data input), in most cases after minimal restructuring for efficient processing (as per the input options).

In addition to or instead of this argument, the model may accept keyword arguments (generally listed after a + separator), which may match the name of a stream (such as 'eeg') in the input data packet (in which case a single-stream packet will be assigned to that argument), or the name of an axis field (e.g., 'TargetValue') of an axis that was promoted to a stream (see the corresponding option under Input, which defaults to promoting the instance axis). In such a case, the variable receives that stream's Block, but reduced to only the axis field in question. An example signature that does this is (data, +, TargetValue, ~) and a signature that binds only a stream named 'eeg' to a keyword argument instead of receiving the data as a whole is (+, eeg, TargetValue, ~). The model may also accept an argument conventionally named 'is_training' either as a second positional argument or as a keyword argument, which will receive False if the model is used in a prediction capacity, and True otherwise.

Your model is generally a graph that begins with one or more Placeholders nodes whose slotname must match a name listed here, and which are followed by a series of nodes that collectively specify your graphical model. The final node of your network must be wired into the "graph" input of the inference node (note that in graphical UIs, the edge that goes into the "graph" input will be drawn in dotted style to indicate that this is not normal forward data flow, but that the graph runs under the control of the inference node). However, the return value of your model has no special meaning since the inference node is generally only concerned with named random variables occurring in the model (i.e., the varnames in Random Draw nodes).

A simple strategy for building a graphical model is to work backwards from the data that you wish to explain or model, and the core tool at your disposal is the Random Draw node, which specifies that the data you want to model (wired in to the obs input port) is the result of a random draw from some (specifiable) distribution (see Distributions package). Models become hierarchical by using distribution parameters that are themselves the output of a random draw. Other useful nodes are the With Stacked Variables node and the associated At Subscripts node. A wide range of other nodes may be used (e.g., math operations, formatting) to complicate the dependency structure among variables in the model.

• verbose name: Graph [Signature]
• default value: (data,~)
• port type: Port
• value type: object (can be None)

n_eff

The effective sample size n_eff of the posterior samples.

• verbose name: N Eff
• default value: None
• port type: DataPort
• value type: dict (can be None)
• data direction: OUT

autocorr

The autocorrelation of the posterior samples.

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

gelman_rubin

The Gelman-Rubin diagnostic R-hat of the posterior samples.

• verbose name: Gelman Rubin
• default value: None
• port type: DataPort
• value type: dict (can be None)
• data direction: OUT

split_gelman_rubin

The Split Gelman-Rubin diagnostic R-hat of the posterior samples.

• verbose name: Split Gelman Rubin
• default value: None
• port type: DataPort
• value type: dict (can be None)
• data direction: OUT

sampler

Optionally the sampler to use for inference.

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

sampler_type

Type of MCMC sampler (Markov transition kernel) to use. Briefly, for models with only continuous latent variables, NUTS should be the default choice as it is efficient and nearly tuning-free. For models of low to moderate dimensionality that have problematic posterior geometry (e.g., a mix of steep and flat regions), the Barker sampler is a more robust but slower fallback. For models with discrete latent variables, the DiscreteHMC sampler is a good choice, unless the number of discrete states is very high, in which case the MixedHMC sampler may be more efficient, but this sampler along with the plain HMC sampler require manual tuning of the HMC pathlength parmameter below. All samplers can also instead be instantiated as a node (one of the Sampler nodes) and wired into the sampler port, in which case this setting should be set to "provided". The sampler nodes each expose a number of options that give complete control over the method used along with documentation. As another option, see also the MCLMC Inference node, which has a similar performance characteristic to MCMC with NUTS, but may handle some models better and others less well.

• verbose name: Sampler Type
• default value: NUTS
• port type: ComboPort
• value type: str (can be None)

trajectory_length

The length of the particle trajectory to simulate. Only used when choosing either the HMC or MixedHMC sampler (but not DiscreteHMC, and ignored if a sampler node is wired in). This value may need to be chosen carefully to avoid either too short (taking very long to converge to a steady state) or too long (well-mixing but generating few samples per amount of compute) trajectories. See also the documentation on diagnostics and history for tips on tuning this.

• verbose name: Trajectory Length (If Hmc/mixed Hmc)
• default value: 6.283185
• port type: FloatPort
• value type: float (can be None)

modified_gibbs

Use the modified Gibbs sampler aka Metropolised Gibbs sampler to sample from discrete latent variables. This is only respected when using either the DiscreteHMC or MixedHMC methods; also ignored if a sampler node is wired in.

• verbose name: Use Modified Gibbs (If Discrete Latents)
• default value: False
• port type: BoolPort
• value type: bool (can be None)

num_warmup

The number of warmup samples to draw. These samples are only used for initial convergence and are discarded from the model. The warmup phase should be set long enough so that the sampling process has settled into a steady state before samples are collected for use as the posterior. There are several diagnostics that can spot insufficiently initialized models ("poorly mixing chains"), and you can also plot the timelines of various model parameters available via the history output.

• verbose name: Number Of Warmup Samples
• default value: 1000
• port type: IntPort
• value type: int (can be None)

num_samples

The number of samples to draw from the posterior distribution. This does not count the warmup samples. This may have to be increased if a sampler is not exploring the parameter space very efficiently (e.g., moving slowly), and likely needs to be higher than 1000 for samplers other than NUTS and HMC, unless you have a low-dimensional model. The resulting increase in memory usage can be counteracted by increasing the "thinning" factor, which subsamples the data.

• verbose name: Number Of Posterior Samples
• default value: 1000
• port type: IntPort
• value type: int (can be None)

num_chains

The number of parallel (independent) markov chains to run. This can be used to accelerate the rate at which samples are drawn, but is also a powerful tool for monitoring convergence of all chains to the same distribution.

• verbose name: Number Of Chains
• default value: 1
• port type: IntPort
• value type: int (can be None)

thinning_factor

The factor by which to reduce the emitted samples. This can be used to reduce the data volume without compromising the quality of the approximation, since it eliminates serially correlated samples. This is also called "thinning" in MCMC terms.

• verbose name: Thinning Factor
• default value: 1
• port type: IntPort
• value type: int (can be None)

freeze_parameters

Whether to freeze parameters into the model, causing the model to be recompiled each time the data changes. This can be enabled if the model fails to compile as a result of having some structural dependency on model arguments (e..g, sometimes parametric plate sizes could cause this).

• verbose name: Freeze All Parameters
• default value: False
• port type: BoolPort
• value type: bool (can be None)

backend_engine

The underlying implementation to use for the MCMC sampler. Numpyro is the recommended default as it natively supports all samplers and their options, and all parts of the modeling workflow, while blackjax serves as a fallback implementation in case of performance issues or other problems with numpyro. Currently blackjax only supports the NUTS, HMC, and Barker samplers.

• verbose name: Sampling Engine
• default value: numpyro
• port type: EnumPort
• value type: str (can be None)

multiprocess_backend

Backend to use for running multiple chains across multiple (CPU) processes. Serial means to not run things in parallel but instead in series (even if num_procs is >1), which can help with debugging, memory usage, or running multiple chains inside a parallel outer loop (e.g., parallel cross-validation, parameter optimization, or parallel foreach). Parallel means to run things across multiple processes using an engine-specific default (for numpyro, this is currently jax.pmap, and for blackjax it is multiprocessing). Vectorized means to run multiple chains in parallel on a single device (CPU or GPU) using SIMD vectorization. The other backends are implementation specific, and currently do not work with both engines; of those, the numpyro engine can be used with jax.pmap, and blackjax can be used with multiprocessing and loky. jax.pmap is a multi-process backend that is mainly configured via jax settings and ignores the other performance options below. Multiprocessing is the simple Python default, but is not the most robust. Loky is a fast and fairly stable backend, but it does not support nested parallelism and has different limitations than multiprocessing. It can be helpful to try either if you are running into an issue trying to run something in parallel. Tip: if you are getting an error that "daemonic processes cannot have children", the most likely cause is that you have two nested parallel loops using multiprocessing, and at least the outer loop needs to be set to nestable.

• verbose name: Multi-Chain Backend
• default value: serial
• port type: EnumPort
• value type: str (can be None)

num_procs

Number of processes to use for running parallel chains. If None, the global setting NUM_PROC, which defaults to the number of CPUs on the system, will be used.

• verbose name: Max Parallel Processes
• default value: None
• port type: IntPort
• value type: int (can be None)

num_threads_per_proc

Number of threads to use for each process when running parallel chains. This can be used to limit the number of threads by each process to mitigate potential churn.

• verbose name: Threads Per Process
• default value: 4
• port type: IntPort
• value type: int (can be None)

num_procs_per_gpu

Number of chains to run on each GPU. This is only relevant if you have GPU compute backends enabled. If your GPU(s) are under-utilized during cross-validation, you can increase this to run this many chains on each GPU.

• verbose name: Processes Per Gpu
• default value: 1
• port type: IntPort
• value type: int (can be None)

conserve_memory

The auto option defaults to 'on' if the multi0chain backend is set to multiprocessing or nestable, and 'off' otherwise. If enabled, then the memory will be cleared periodically across loop iterations. This is useful if you are running out of memory during a run, but it will slow down the computation somewhat. The aggressive mode will force memory to be cleared after each iteration, which has the highest overhead, but guarantees a minimal memory footprint. However, the multiprocessing backend is known to occasionally hang in this mode so this may be reverted to on if you experience hangs. The off mode will leave memory reclamation to the individual nodes and scheduler behavior within the loop body, which may be further tuned using e.g. the default_conserve_memory config-file setting or per-node settings.

• verbose name: Conserve Memory
• default value: auto
• port type: EnumPort
• value type: str (can be None)

serial_if_debugger

If True, then if the Python debugger is detected, the node will run in serial mode, even if multiprocess_backend is set to something else. This is useful for debugging, since the debugger does not work well with parallel processes. This can be disabled if certain steps should nevertheless run in parallel (e.g., to reach a breakpoint more quickly).

• verbose name: Serial If Debugger
• default value: True
• port type: BoolPort
• value type: bool (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)

posterior_correlations

Assumed covariance structure among posterior variables. This setting is used by the inference methods to improve the tractability of posterior inference: 'uncorrelated' assumes that all posterior variables are uncorrelated (i.e., diagonal posterior covariance); 'all-to-all' does not restrict the covariance structure in any way but can be computationally costly, and 'blockwise' allows one to specify which variables in the model may be mutually correlated and or have internal correlations (if multivariate). For example, the syntax 'blockwise(myvar1/myvar2,myvar3)' expresses that myvar1 and myvar2 are assumed to be correlated with each other but not with myvar3, but each of the three variables may have its own internal crrelation structure, while any variables not listed are treated as uncorrelated. Note that, while this setting improves the efficiency of the inference (in terms of the effective sample size per unit of compute) by determining the form of the "mass matrix", it does not otherwise impact the fidelity of the final posterior once inferred.

• verbose name: Posterior Correlations
• default value: uncorrelated
• port type: ComboPort
• value type: str (can be None)

init_strategy

Override the initialization strategy for distribution parameters, optionally for individual (sets of) variables. Some choices accept a parameter that can also be omitted (the default is shown in the drop-down examples). Uniform(r) initializes each parameter to a uniform range within -r to +r in the "unconstrained" domain, which is very frequently a good default, although at times the system may have to make multiple attempts to find a feasible starting point. At times, models can require a more conservative choice, for example median(n) initializes to the median of n samples drawn from the prior distribution, mean uses the expected value, sample draws a random sample, feasible initializes to a fixed trivially feasible point (e.g., 0), and value(x) initializes to a given fixed value x. This can also be specified on a per-variable basis (but typically not necessary for well-specified models), using a dictionary syntax where the variable name (or a wildcard pattern) is used as the key and the value is the initialization form. See also drop-down options for concrete examples.

• verbose name: Init Strategy
• default value: uniform
• port type: ComboPort
• value type: str (can be None)

promote_axis

If given, promote axes of the specified type to their own stream using the Promote Axis to Stream node. This adds a new stream to the data packet that holds the data of the selected axis; It has a feature axis that indexes the fields of the axis (e.g., 'TargetValue', 'times', etc) and a (blank) dummy copy of the axis as the second dimension, and the axis "payload" (i.e. numeric content) is then accessible in the stream's two-dimensional data array like any other data modality. This representation is generally used in contexts that employ high-performance (multicore or GPU-accelerated) computation, including the Deep Model, Convex Model, and Inference nodes. This can be disabled by leaving the option blank (but note that doing so can incur heavy performance overhead each time the axis content changes from one use of the node to another, e.g., in a cross-validation). You can also disable this you wish to manually use the Promote Axis to Stream or other formatting node beforehand. The new stream is by convention named the same as the axis (i.e., 'instance'), unless there are multiple different streams with matching axes that are not equal to each other, in which case one stream per source stream is created and is named 'streamname-axisname'. The original axis will be cleared to all-defaults for the purpose of running the model graph, but will be restored afterwards from the stream (if modified during inference) or the original axis.

• verbose name: Promote Axis To Stream
• default value: instance
• port type: ComboPort
• value type: str (can be None)

pass_metadata

Graph accesses marker-stream or props metadata. If this is selected, then marker streams and stream (chunk) properties will be preserved when the input data enters the model graph. If this is deselected (the default), both any marker streams and all but a few essential chunk properties will be removed for the purposes of inference (which avoids unnecessary recompilation of the model graph, but the model will not have access to these details) and are restored afterwards.

• verbose name: Pass Marker/props Metadata
• default value: False
• port type: BoolPort
• value type: bool (can be None)

data_format

The type of statistics to output in the main data output packet (for prediction use cases). This can either be a comma-separated list of summary statistics, in which case the data output will contain a statistic axis along which the respective statistics are itemized, or it can be set to distribution, in which case the output will have a distribution axis along which the desired number of posterior samples are enumerated. The former is useful for a simple estimate-with-error-bars type of representation, which can then be used for plotting etc. If a single location statistic is used (e.g., mean or median), then the output will be largely compatible with the output of a conventional machine learning node (which tend to output a posterior mode or maximum-likelihood estimate depending on the type of model), and the inference node can be used as a drop-in replacement for such nodes. When error statistics are included (e.g., stddev, mad, or ci90), only a few successor nodes will correctly interpret or preserve this output, for example some of the plotting nodes that can display error bars; other numeric nodes will either ignore these statistics (e.g., MeasureLoss) or will act on all statistics using the same operation, which is typically not correct. Instead, if further downstream computations are to be performed with the output of the inference node, it is recommended to use the distribution output, since posterior samples will propagate through most mathematical operations correctly, i.e., the result will be a distribution over the result of the successor operation(s).

• verbose name: Data Output Statistics
• default value: distribution
• port type: ComboPort
• value type: str (can be None)

num_pred_samples

Number of samples to use when computing predictive statistics (content of the data output). Note that for machine-learning use cases, i.e., generation of test-set predictions, not many samples are typically needed, especially when the predictive distribution is reduced via summary statistics. A sensible choice may be a power of two, e.g., between 32 and 256, although this will depend on the dimensionality of the output space.

• verbose name: Num Prediction Samples
• default value: None
• port type: IntPort
• value type: int (can be None)

data_vars

Optionally a listing of variables for which to generate predictions. By default this will be all variables that are not included in the posterior distribution (what is returned by the dist and samples outputs), which in practice amounts to all observable variables in the model. In general, the node will name the streams in the packet based on the variable (e.g., 'y') and if the respective Random Draw node was configured via a like= input to output a Packet, then this stream name will be concatenated to the variable name (e.g., 'y_eeg'). To take control of the output stream names, one may also specify this as a dictionary, where the keys are the variable names whose data to emit and the values are the desired output stream names (e.g., {'y': 'eeg']).

• verbose name: Data Output Variables
• default value: None
• port type: Port
• value type: object (can be None)

exclude_from_posterior

Optionally a listing of latent variable names or patterns to exclude from the posterior. It is recommended to use patterns that end in a * to also cover cases where additional related variables, such _decentered, are present in the model. Among others, this can be used with latent variables that take on a different shape at prediction time to prevent shape mismatches. Such variables will then be distributed as per their governing distribution parameters (or their posterior distributions).

• verbose name: Exclude From Posterior
• default value: None
• port type: ListPort
• value type: list (can be None)

vectorized_prediction

The way in which samples are handled during prediction from new data and generation of predictive statistics. Note that both modes are compiled and will run efficiently, but the vectorized mode can be considerably faster with small (low-dimensional / few samples) models. For high-dimensional models, the memory requirements of the vectorized mode can be very large and the mode is not necessarily faster, so the serial mode is recommended in such cases.

• verbose name: Vectorized Prediction
• default value: serial
• port type: EnumPort
• value type: str (can be None)

canonicalize_output_axes

Whether to canonicalize the data output axes of the node to match the expected output axes of other machine-learning nodes. This only applies to the data output (predictions) and only if the model outputs data with an instance axis. This is mainly useful if you use the Inference node in an ML workflow (MeasureLoss, Crossvalidation, Parameter Optimization) and ensures that the output has a feature axis that properly encodes what the outputs represent. If the observable variables in your model have highly custom axes (other than one instance and optionally a feature axis), you may need to do some extra reformatting between the Inference node and any downstream ML workflow node.

• verbose name: Canonicalize Output Axes
• default value: True
• port type: BoolPort
• value type: bool (can be None)

seed

Seed for any pseudo-random choices during training. This can be either a splittable seed as generated by Create Random Seed or a plain integer seed. If left unspecified, this will resolve to either the current 0-based "task number" if used in a context where such a thing is defined (for example cross-validation or a parallel for loop), or 12345 as a generic default.

• verbose name: Random Seed
• default value: None
• port type: Port
• value type: AnyNumeric (can be None)

update_on

Update the model on the specified data. This setting controls how the node behaves when it is repeatedly invoked with data and can usually be left at its default. For use cases in which the node is invoked only a single time in a pipeline, all settings are equivalent. Scenarios where a difference arises include 1) real-time (streaming, aka "online") processing, where initially a non-streaming ("offline") dataset is passed in or a previously trained model is loaded in), and subsequently streaming data is passed through the node, 2) machine-learning style offline analysis, where the node is first given an offline dataset to train on, and then subsequently given a (still offline) test dataset to evaluate the trained model on, or 3) when the model is adapted over the course of multiple successive invocations with potentially different datasets. The settings are then as follows: "initial offline" will adapt the model only on the first non-streaming data that it receives (note that whether data is considered streaming or not is a matter of whether its is_streaming flag is set, rather than whether it comes in in actual real time). The "successive offline" mode will keep updating the model on any data marked non-streaming (this will use the model's prior state if none is wired in, or the wired-in state, which therefore must come from a previous invocation of the model). The "offline and streaming" mode will train on any data, regardless of whether it is offline or streaming (e.g., for adaptive real-time training). Note that not all inference nodes will support the offline and streaming mode -- specifically, MCMC Inference does not. The parameter can also be changed at runtime, to switch from one mode to another.

• verbose name: Update On
• default value: initial offline
• port type: EnumPort
• value type: str (can be None)

dont_reset_model

Do not reset the model when the preceding graph is changed. Normally, when certain parameters of preceding nodes are being changed, the model will be reset. If this is enabled, the model will persist, but there is a chance that the model is incompatible when input data format to this node has changed.

• verbose name: Do Not Reset Model
• default value: False
• port type: BoolPort
• value type: bool (can be None)

verbosity

Verbosity level. Higher numbers will produce more extensive printed output.

• verbose name: Verbosity Level
• default value: 1
• port type: EnumPort
• value type: str (can be None)

axis_pairing

Axis pairing override to apply within the context of the model. This will cause all nodes in the model graph that have an axis_pairing option set to 'default' to use this setting instead. It is recommended to leave this to 'matched'; if set to positional, several options in model nodes need to be carefully chosen in correspondence with the axis position in the data, including the number of event-space dimensions in AtSubscript nodes, and the dimension index (relative to the event-space dimension) for any With Stacked Variables nodes. One also needs to be careful with whether distributions have a multivariate event space (e.g., Multivariate Normal) or not (most other distributions).

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

check_diagnostics

Diagnostics that should be automatically checked to ensure convergence; note the diagnostics are also available as outputs on the node for analysis by your own pipeline. General guidelines are: Gelman-Rubin (R) around 1.00 (ideally below 1.01) indicates good convergence, less than 1.05 is acceptable but careful inspection (eg history plots) is recommended, and greater than 1.1 indicates poor convergence or "mixing" of chains (steady-state exploration of the posterior distribution). For split Gelman-Rubin criteria are similar, but additionally, if this is significantly greater than 1 but R is close to 1, this can indicate lack of stationarity. An effective sample size (ESS) of 1000 or more is esxcellent, greater than 100 is generally considered acceptable, and ESS less than 100 suggests high autocorrelation, slow mixing, and potential issues with the efficiency of the sampler. The relative ESS (rESS) is mostly a measure of your sampler's efficiency, where a value greater than 0.5 is excellent, greater than 0.1 is reasonable, and less than 0.1 indicates inefficient exploration of the posterior and high autocorrelation. These diagnostics can also be used to hand-tune the trajectory length when using HMC-type samplers like HMC or MixedHMC; if R is greater than 1.05 or ESS is less than 100, consider increasing the trajectory length.

• verbose name: Check Diagnostics
• default value: ['gelman-rubin', 'eff. sample size', 'relative ESS']
• port type: SubsetPort
• value type: list (can be None)

differentiation_mode

The differentiation mode to use. Forward is supported by all constructs that may occur in a model. Reverse can be more efficient depending on the ratio of data points to parameters, but is not supported for example when Fold Loops are used in the model (e.g., for time-series models), and will throw an error in such cases.

• verbose name: Differentiation Mode
• default value: reverse
• port type: EnumPort
• value type: str (can be None)

history_fields

Additional diagnostic history to collect and output. Note that not every sampler type supports every field. All samplers (NUTS, HMC, Barker) traverse a potential energy function (negation of the log posterior density), and do so in an unconstrained transformation of the model's latent-variable space. The associated state variables are z (the current coordinate in unconstrained space), potential_energy (the potential value at z where lower means more probable regions of the posterior), z_grad (the gradient of the potential energy with respect to z), r (the current momentum vector for HMC/NUTS), energy (total of potential and kinetic energy, only for HMC/NUTS; expected to be constant except for discontinuities whenever the sampler chooses a new trajectory), the used trajectory length (HMC only), the acceptance probability of the current proposal and the mean acceptance probability from start to now during warmup (higher is better). For DiscreteHMC and MixedHMC, the fields (except z and accept_prob, for MixedHMC) pertain to the underlying HMC sampler's state. The diverging flag indicates whether the current trajectory is diverging.

The results are generally available via the output port called history in packet form, and have a leading unnamed axis of length num_chains with label 'chains' to index the chain, a time axis that indexes the (wall-clock) timeline of the history trace, and any other axes relevant for the variable in question, if it is multivariate. Note also that the k'th sample in the returned samples corresponds to the k's history entry (along its time axis) and specifically the k'th z value, where z lives in unconstrained space and the sample lives in the original parameter space of the model.

If you are using plain HMC or MixedHMC, these state traces can be used to tune the trajectory length: if you observe chains that seem to get "stuck" in one regime of the parameter space for extended periods before moving to other regimes and back, you should increase the trajectory length. If you chains are in a steady-state regime (mixing well), you could potentially reduce the trajectory length and check whether the sampler is still mixing well with a lower setting, which will be more computationally efficient.

• verbose name: Return History Of
• default value: []
• port type: SubsetPort
• value type: list (can be None)