← bayesian package

MCLMCInference

Apply Bayesian inference given data and a wired-in statistical model, using the Micro-Canonical Langevin Monte Carlo (MCLMC) approach.

This method has a similar or potentially somewhat better performance characteristic as the MCMC Inference node in conjunction with the NUTS sampler, but the specific behavior will depend on the model and data. MCLMC may also be somewhat more GPU-friendly than the samplers offered by the MCMC node. This makes the MCLMC method a good second choice to try if the NUTS sampler diverges or is too slow, especially with high-dimensional problems and time-consuming analyses. This method cannot currently handle discrete latent variables (but discrete observed variables are fine). The MCLMC node is relatively robust and tuning-free, and comes in two main variants: unadjusted and Metropolis-adjusted. Typically the unadjusted variant is understood to be more efficient, and the variant can be fine tuned to a limited extent via the desired energy variance parameter and a few related parameters (see parameter group). The Metropolis-adjusted variant is instead tuned via the desired acceptance probability and related parameters, and is asymptotically unbiased, but can be computationally more expensive, approaching that of Metropolis-Hastings MCMC (e.g., NUTS). The node offers a range of performance options mainly for the multi-chain mode, which is primarily of interest for convergence diagnostics and monitoring (a good setting is 4 chains). MCLMC provides the usual MCMC-type diagnostics and numerous history fields that play mostly the same role as in MCMC, and which can be useful for understanding the behavior and performance of the sampler. Consider disabling the automatic retries during model development since those can mask other issues. Additional tuning knobs are the number of warmup and posterior samples to generate, and the init strategy. For additional model troubleshooting tips, see also the documentation of the MCMC node. 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 node's samples outputs port. The node evaluates diagnostics by default (but keep in mind that the main diagnostics require multiple chains to be configured, which is not the default). 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 nodes 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. 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 0.9.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

num_warmup

The number of warmup samples to draw. This is used to tune the momentum decoherence scale L and the step size epsilon. These samples are only used for initial convergence and are discarded from the model, and there is no memory cost associated with them. Burn-in is usually quite fast per sample, and 10k samples can relatively easily be drawn on a GPU.

• verbose name: Number Of Warmup Samples
• default value: 10000
• 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. Memory utilization is proportional to this, so high-dimensional models will be limited in this. Note that the Langevin process draws one sample per step, whereas HMC/NUTS take multiple steps until a sample is drawn; therefore, MCLMC is considerably faster at generating a given desired number of samples.

• verbose name: Number Of Posterior Samples
• default value: 1000
• 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)

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)

metropolized

Whether to use the Metropolis-adjusted version of the sampler; yielding a form of Metropolis-Hastings Microcanonical Hamiltonian Monte Carlo (MH-MHMC). Enabling this causes the algorithm to be asymptotically unbiased, at some (perhaps considerable) extra computational cost. Since the bias of unadjusted MCLMC is not typically very large, there is little practical advantage to enabling this step per se, except for the fact that, when enabled, an alternative tuning strategy is used that employs the desired acceptance probability like in other MCMC samplers. That parameter can be easier to interpret or tune than the desired energy variance (which is the tunable parameter that is used with unadjusted MCLMC).

• verbose name: Metropolis-Adjusted
• default value: False
• port type: BoolPort
• value type: bool (can be None)

tuning_fractions

The fractions of the warmup steps to allocate to each of the three stages of parameter tuning. Note the remainder leaves additional samples to burn in the sampler state. These typically do not need adjustment.

• verbose name: Tuning Fractions
• default value: [0.1, 0.1, 0.1]
• port type: ListPort
• value type: list (can be None)

diagonal_preconditioning

Whether to use diagonal preconditioning for the tuning of the step size. This is generally recommended for high-dimensional problems.

• verbose name: Diagonal Preconditioning
• default value: True
• port type: BoolPort
• value type: bool (can be None)

desired_energy_variance

The desired energy variance for MCLMC to aim for while auto-tuning. It is recommended to start with a small value (like the default) and gradually increase it (for example by doubling it) if you see the chain stalling or taking a very long time.

• verbose name: Target Energy Variance
• default value: 0.0005
• port type: FloatPort
• value type: float (can be None)

trust_in_estimate

The trust in the estimate of the optimal step size. This impacts how quickly the algorithm will adjust to the estimated step size.

• verbose name: Trust Factor
• default value: 1.5
• port type: FloatPort
• value type: float (can be None)

num_effective_samples

The number of effective samples to aim for when tuning the step size. A value greater than 100 is generally considered adequate for moderate-dimensional problems at reasonable fidelity. For very high-fidelity fits and post-hoc statistics or when dealing with very high-dimensional models, values as large as 1000 could be used.

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

desired_accept_prob

The desired acceptance probability for step-size adaptation. The default is generally a good recommendation, but this parameter can be adapted by the user. This will adjust the step size such that on average a step is accepted (within the posterior distribution) with this probability. Increasing this value will lead to a smaller step size, thus the sampling will be slower but more robust.

• verbose name: Target Accept Prob.
• default value: 0.9
• port type: FloatPort
• value type: float (can be None)

random_trajectory_length

Whether to use a randomized trajectory length for the Langevin dynamics. Recommended.

• verbose name: Random Trajectory Length
• default value: True
• port type: BoolPort
• value type: bool (can be None)

adapt_to

Whether to adapt to the average-case or worst-case posterior variance. The authors recommend using the average-case adaptation, which achieves a more balanced adaptation too different aspects of the posterior distribution. However, if the inference struggles with one variable in particular, it could be worth a try to switch to worst-case optimization. The rule amounts to whether the average or maximum eigenvalue of the covariance matrix is used for the adaptation.

• verbose name: Adapt To
• default value: average-case
• port type: EnumPort
• value type: str (can be None)

num_adaptation_passes

The number of adaptation passes ("windows)" to use. Typically one is enough, although a seriously struggling model might benefit from more as a last resort.

• verbose name: Num Adaptation Passes
• default value: 1
• port type: IntPort
• value type: int (can be None)

trajectory_expansion_factor

The factor by which the trajectory is expanded relative to the empirically estimated trajectory length. This is typically somewhat larger than 1.0 to account for the fact that the empirical estimate may be overly conservative. A larger value will explore the posterior somewhat more aggressively, but may also lead to more divergences. The default is a good starting point, and this parameter may in general not need much (if any) tuning, except as a last resort tuning knob.

• verbose name: Trajectory Expansion Factor
• default value: 1.3
• port type: FloatPort
• value type: float (can be None)

multiprocess_backend

Backend to use for running multiple chains across multiple (CPU) processes. Multiprocessing is the simple Python default, which is not a bad start. Nestable is a version of multiprocessing that allows your pipeline to itself use parallel computation. If you are getting an error that "daemonic processes cannot have children", the most likely cause is that you have two nested parallel loops, and at least the outer loop needs to be set to nestable. 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. Serial means to not run things in parallel but instead in series (even if num_procs is >1), which can help with debugging. Threading uses Python threads in the same process, but this is not recommended for most use cases due to what is known as GIL contention.

• 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)

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)

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)

max_retries

The maximum number of times to retry the fitting in case of divergence. Note that this can mask problems with the model, so it is a good idea to monitor the logs for potential retries having happened.

• verbose name: Max Retries
• default value: 5
• port type: IntPort
• value type: int (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)

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. The MCLMC sampler traverses a potential energy function (negation of the log posterior density) and uses coordinates that are in an unconstrained transformation of the model's latent-variable space. Unlike HMC, the sampler proceeds primarily along contours of the potential energy (with random energy-preserving perturbations to explore different level sets). 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), and r (the current momentum vector). Specific to the unadjusted MCLMC sampler, the history can also include energy_change (the change in total energy), and kinetic_change (the change in the kinetic energy); for the adjusted MCLMC sampler, the history can include accept_prob (the acceptance probability of the step), diverging (a boolean indicating whether the step was divergent), num_steps (the number of integration steps taken in the trajectory), and energy (sum of potential and kinetic energy).

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.

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