← machine_learning package

R2D2BayesianClassification

Classify data instances using sparse Bayesian logistic regression with the R2-D2 prior.

The R2-D2 prior does not start by assigning a prior directly to each coefficient. Instead, it places a prior on the overall model fit, measured by Bayesian R^2, and then decomposes the corresponding coefficient variance across features by means of a sparse Dirichlet allocation. This leads to a model that encourages a small number of features to absorb most of the signal while shrinking the remainder strongly toward zero. Compared with the regularized horseshoe, R2-D2 gives a more direct way to express beliefs about overall model fit and feature sparsity. The mean_r2 and precision_r2 parameters determine how strongly the prior favors weak or strong predictive signal in the data, while the expected relevant features parameter determines how concentrated the variance decomposition is across coefficients. In logistic regression, the exact induced prior on the global coefficient variance is not available in closed form. This node therefore uses a generalized beta-prime approximation to that prior, following Yanchenko, Bondell, and Reich (2025), and then fits the resulting model with the No-U-Turn Sampler (NUTS). NUTS is slower than variational approximations but is currently the most defensible inference strategy for this hierarchy and gives high-quality posterior estimates on low- to moderate-dimensional problems. Like all machine learning methods, this method needs to be calibrated ("trained") before it can make any predictions on data. For this, the method requires training instances and associated training labels. The typical way to get such labels associated with time-series data is to make sure that a marker stream is included in the data, which is usually imported together with the data using one of the Import nodes, or received over the network alongside with the data, e.g., using the LSL Input node (with a non-empty marker query). These markers are then annotated with target labels using the Assign Targets node. To generate instances of training data for each of the training markers, one usually uses the Segmentation node to extract segments from the continuous time series around each marker. Since this machine learning method is not capable of being trained incrementally on streaming data, the method requires a data packet that contains the entire training data; this training data packet can either be accumulated online and then released in one shot using the Accumulate Calibration Data node, or it can be imported from a separate calibration recording and then spliced into the processing pipeline using the Inject Calibration Data, where it passes through the same nodes as the regular data until it reaches the machine learning node, where it is used for calibration. Once this node is calibrated, the trainable state of this node can be saved to a model file and later loaded for continued use. More Info... Version 0.7.0

Ports/Properties

data

Data to process.

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

cond_field

The name of the instance data field that contains the conditions to be discriminated. This parameter will be ignored if the packet has previously been processed by a DescribeStatisticalDesign node.

• verbose name: Cond Field
• default value: TargetValue
• port type: StringPort
• value type: str (can be None)

feature_scaling

Feature scaling to use. The R2-D2 prior acts on coefficient variance, so the features should be on roughly comparable scales for the prior to shrink coefficients in a meaningful way. Standardization is the recommended default for most data.

• verbose name: Feature Scaling
• default value: std
• port type: EnumPort
• value type: str (can be None)

mean_r2

Mean of the Beta prior on Bayesian R^2, the prior expected model fit. Lower values encode a stronger preference for weak overall signal; higher values encode a prior belief that the features explain a larger fraction of the outcome variability. The default of 0.5 is appropriate for easy to moderate classification problems. For harder problems with lower signal-to-noise ratio, reduce to 0.3-0.4 to place more prior mass near R^2 = 0; for high-dimensional settings (p >> n), values below 0.3 are recommended (Yanchenko et al., 2025).

• verbose name: Mean R-Squared
• default value: 0.5
• port type: FloatPort
• value type: float (can be None)

precision_r2

Precision of the Beta prior on Bayesian R^2. Larger values make the prior on overall model fit more concentrated around mean_r2, whereas smaller values yield a broader, less informative prior. For harder classification problems (lower signal-to-noise ratio), increasing precision to 3.0 while lowering mean_r2 can encode a more confident prior belief about weaker signal.

• verbose name: R-Squared Precision
• default value: 2.0
• port type: FloatPort
• value type: float (can be None)

expected_relevant_features

Expected number or fraction of relevant features. Controls how the prior distributes coefficient variance across features: smaller values concentrate the variance on fewer features (stronger sparsity), while larger values spread it more evenly. Values between 0 and 1 (exclusive) are interpreted as a fraction of the total feature count; for instance, 0.1 means that roughly 10%% of features are expected to be relevant. Values >= 1 must be integers and are interpreted as an absolute count; for instance, 5 means that roughly 5 features are expected to be relevant. For this method, absolute counts (e.g., 5 or 10) often work well because the MCMC sampler can learn the variance decomposition from data even with a relatively permissive prior.

• verbose name: Expected Relevant Features
• default value: 0.1
• port type: FloatPort
• value type: float (can be None)

sample_size_factor

Sample size correction factor or effective sample size. When observations are not independent (e.g., multiple trials per participant), the effective information content may be considerably lower than the nominal sample count, causing the posterior to be overconfident. This parameter tempers the likelihood by the factor n_eff/n, reducing the data's influence on the posterior to match the effective information content. Values between 0 and 1 (inclusive) are interpreted as a multiplicative factor applied to the actual number of observations; for instance, if you have 2000 trials from 30 participants, set this to 30/2000 = 0.015. Values > 1 must be integers and are interpreted as an absolute effective sample size; for instance, 30 means that the effective sample size is 30 regardless of the actual number of observations.

• verbose name: Sample Size Correction
• default value: 1.0
• port type: FloatPort
• value type: float (can be None)

include_bias

Include a bias (intercept) term. If false, features need to be centered or include a constant feature set to 1.

• verbose name: Include Bias Term
• default value: True
• port type: BoolPort
• value type: bool (can be None)

gbp_regularization

Regularization strength for an internal approximation step that converts the R-squared prior into a form suitable for MCMC sampling. Larger values make the approximation more conservative and stable, while smaller values allow a closer fit to the theoretical prior at the risk of numerical instability. The default of 0.25 works well in most cases. This is a technical parameter that rarely needs adjustment.

• verbose name: Gbp Regularization
• default value: 0.25
• port type: FloatPort
• value type: float (can be None)

num_warmup

Number of NUTS warmup (burn-in) steps. During warmup the sampler adapts its step size and mass matrix. 500 is generally sufficient; for low-dimensional problems (p < 50) this can be reduced to 200-300 to save time.

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

num_mcmc_samples

Number of NUTS posterior samples to draw after warmup. More samples yield more precise posterior estimates but increase runtime. For low-dimensional problems (p < 50), 200-300 samples are often adequate.

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

random_seed

Random seed. Different values may give slightly different outcomes.

• verbose name: Random Seed
• default value: 12345
• port type: IntPort
• value type: int (can be None)

initialize_once

Calibrate the model only once. If set to False, then this node will recalibrate itself whenever a non-streaming data chunk is received that has both training labels and associated training instances.

• verbose name: Calibrate Only Once
• default value: True
• port type: BoolPort
• value type: bool (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)

probabilistic

Use probabilistic outputs. If enabled, the node will output for each class the probability that a given trial is of that class; otherwise it will output the most likely class label.

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

verbosity

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

• verbose name: Verbosity Level
• default value: 0
• 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)