Estimators¶

R-MSRM and GP-MSRM have different inference and prediction contracts. Start with the choice guide; use capabilities for supported combinations. Inherited scikit-learn get_params and set_params follow the standard estimator interface.

MultimodalSRM¶

from multimodalsrm import MultimodalSRM · Source

MultimodalSRM(
    features=10,
    *,
    latent_dt,
    responses=None,
    latent_pooling="shared",
    latent_strength=1.0,
    modality_weights=None,
    loading_ridge=0.001,
    loading_penalty_scaling="pair",
    latent_ridge=0.0001,
    temporal_strength=0.01,
    max_iter=100,
    tol=1e-05,
    n_init=1,
    n_jobs=1,
    init="random",
    random_state=None,
    gap_threshold=None,
    kernel_max_iter=50,
    balance_scale=True,
)

Regularized multimodal factor model; arrays are time by feature.

By default, one latent response per run is shared exactly across participants and modalities, with separate participant–modality maps and response kernels. affinity_ represents this sharing as a complete graph with unit edges; exact equality is enforced independently of latent_strength.

Penalties and balancing conventions are recorded in configuration_. Reaching max_iter does not constitute convergence. init="hybrid" uses one deterministic spectral start followed by paired random starts; init="spectral" repeats the same start redundantly at every restart.

n_jobs runs independent restarts in isolated processes (default 1; -1 uses available CPUs, capped by n_init). Integer random_state preserves restart seeds and selection across worker counts. Native parallel cross-validation suppresses inner restart workers to avoid oversubscription.

MultimodalSRM.fit¶

MultimodalSRM.fit(data, y=None, *, affinity=None)

MultimodalSRM.infer_latent¶

MultimodalSRM.infer_latent(data, *, times=None)

MultimodalSRM.predict¶

MultimodalSRM.predict(data, *, targets, source="within", times=None)

MultimodalSRM.calibrate¶

MultimodalSRM.calibrate(data, **kwargs)

MultimodalSRM.kernel¶

MultimodalSRM.kernel(modality, subject=None, level="subject", times=None)

MultimodalSRM.plot_kernels¶

MultimodalSRM.plot_kernels(modality, show_subjects=True, ax=None)

BayesianMultimodalSRM¶

from multimodalsrm.bayesian import BayesianMultimodalSRM · Source

BayesianMultimodalSRM(
    *,
    priors,
    anchor=None,
    features=1,
    factor_anchors=None,
    reference_modality=None,
    responses=None,
    length_scale=3.0,
    inference="posterior",
    search=None,
    sampler=None,
    sample_blocks=None,
    random_state=0,
    max_observations=800,
    covariance_tolerance=1e-07,
    linear_algebra="dense",
    spectral=None,
    run_baseline_sd=None,
    noise_timescales=None,
    response_quadrature_order=None,
    state_space_gaussian="auto",
)

Experimental Bayesian SRM with a shared GP timescale.

features>1 supports MAP with dense/grouped/state_space algebra. Optional factor_anchors select a training QR reporting rotation; without them, the fitted optimizer coordinates are retained. Explicit anchors must name one observed training feature per factor, starting with anchor when supplied. Raw optimizer parameters remain unchanged. For MAP coordinates, use loadings W_raw @ configuration_['factor_orientation']['rotation']. All factors share modality filters and GP timescale. Multifactor posterior supports dense/grouped Identity/Gaussian responses, plus Gamma/DoubleGamma/BatemanSCR with explicit response quadrature, with white noise and explicit training anchors. reported_parameter_draws() applies a separate positive-diagonal QR to each draw; raw draws and diagnostics are unchanged. Latent mixtures use the same draw-specific coordinates and full conditional covariance in each projection. These are reporting conventions only. Multifactor spectral mode and run baselines remain unsupported. Full dense/grouped posterior supports explicit joint donor/participant updates. sample_latent returns joint conditional trajectory draws.

priors describes loadings, offsets, noise variance and free response parameters. A numeric length_scale fixes the latent GP correlation timescale in timestamp units. Pass a Prior with positive finite bounds to learn one shared timescale, keeping latent variance fixed at one. This supports dense/grouped MAP and posterior with Identity/Gaussian responses or quadrature Gamma/DoubleGamma/BatemanSCR, independent noise and no run baselines. It is not a response width. Optional anchor=(subject, modality, feature) sets a positive loading for one factor; otherwise the first sorted eligible training feature is used. The anchor may have any supported response family. Optional reference_modality selects a fixed lag (shape may be learned). Otherwise an already fixed lag is used if available; with all lags free, proper supplied priors define the common offset and relative lag summaries subtract the across-modality mean. Latent queries and lag priors/bounds remain in model-clock coordinates. No convention establishes physiological timing or identifies disconnected data components. The model consumes supplied units without standardization. MAP and NUTS share a proper physical parameter density and marginalize the latent GP. Sampling diagnostics do not establish calibration or complete mode coverage.

linear_algebra="grouped" opts into an exact reduction over repeated modality/time functionals. "dense" remains the default reference. Both paths retain the original scalar-observation capacity guard.

linear_algebra="state_space" uses exact Matérn-3/2 Kalman inference with stationary initialization and native observation times. It groups filtering and smoothing updates at exact modality/time nodes for fixed or learned responses when the noise prior has strictly positive support. Noise priors admitting zero retain scalar updates. MAP supports Identity, Gaussian, or integer-shape Gamma/DoubleGamma responses and independent observation noise. Widths/scales, undershoot ratios, and lags may be learned; Gamma shapes remain fixed. Gaussian responses use a qualified rational approximation; Gamma tails are restored. A temporal covariance error bound is checked over the full declared parameter domain against covariance_tolerance. state_space_gaussian="auto" tries compact rational banks before the larger Laguerre representation; either method can be requested explicitly. BatemanSCR learns rise, decay and lag with two response states and an explicit bound for the restored 90-second tail. SampledKernel remains unsupported. Prediction uses an RTS smoother; no dense observation covariance is built. The explicit max_observations guard still applies and can be raised.

linear_algebra="spectral", spectral=SpectralConfig(rank, padding) explicitly approximates the GP with a padded sine basis. Its finite rank and boundary errors require separate numerical and posterior validation. Boundaries can introduce spurious common-lag likelihood dependence; this does not establish absolute physiological timing. Gaussian coefficients are marginalized exactly within that approximation.

response_quadrature_order explicitly enables finite response-functional quadrature for Gamma, DoubleGamma, BatemanSCR (and Gaussian/Identity). Orders 8..1024 are per integration panel. This path supports dense/grouped MAP and posterior sampling, including continuous shape estimation. The latent process remains continuous; response integrals and L2 norms are approximate. covariance_tolerance does not certify this path: compare higher orders and independent integrals for the declared bounds. Approximation metadata is retained in configuration, queries and archives.

run_baseline_sd={modality: sd} optionally adds independent zero-mean Gaussian offsets per participant/run/feature, in supplied observation units. Their fixed prior SDs are explicit; offsets are analytically marginalized. Dense/grouped calculations support them; spectral does not yet. Prediction includes baseline uncertainty even with include_noise=False; the shared latent excludes these offsets. None/zero preserves the original model.

BayesianMultimodalSRM.fit¶

BayesianMultimodalSRM.fit(
    data,
    y=None,
    *,
    progress=None,
    search_progress=None,
    warmup_checkpoint=None,
    resume_warmup=False,
)

Fit the model; search_progress receives restart and iterate MAP checkpoints.

The existing progress callback retains its phase timing event format. For full dense/grouped posterior training, warmup_checkpoint saves the complete sampler state after warmup. Set resume_warmup=True to reuse it with identical data, settings, source, and runtime. An explicit integer random_state is required; existing checkpoint paths are never overwritten.

BayesianMultimodalSRM.condition¶

BayesianMultimodalSRM.condition(
    donors,
    *,
    targets,
    donor_layout="runs",
    mode="joint",
    progress=None,
)

Condition independent new runs after removing target payloads.

mode="joint" (default) refits training plus current donors. mode="frozen" uses the original training MAP without optimization or sampling and conditions each new run's common GP on current donors. Frozen mode requires a MAP fit; uncertainty excludes parameter uncertainty. Returns an independent estimator. Chained calls retain the training/calibration reference and replace the current donor batch. Target payloads are removed before validation and support selection.

BayesianMultimodalSRM.relative_lag_draws¶

BayesianMultimodalSRM.relative_lag_draws()

Relative modality lags, in timestamp units (normally seconds).

Return read-only arrays with the original (chain, draw) axes, including fixed modalities. MAP gives shape (1, 1). A fixed reference lag is subtracted when available. Without one, subtract the across-modality mean separately for each draw, preserving all pairwise differences. This centers summaries only: latent query times and lag priors remain in model coordinates. It does not establish absolute timing identification or calibrated uncertainty.

BayesianMultimodalSRM.predict¶

BayesianMultimodalSRM.predict(*, times, include_noise=False, max_draws=200)

Query excluded targets after condition; default 200 mixture draws.

Output nesting is subject/run/modality. max_draws=None uses all retained draws; otherwise selection is balanced across chains.

BayesianMultimodalSRM.calibrate¶

BayesianMultimodalSRM.calibrate(data, *, search=None, random_state=None, progress=None)

Fit one new participant against the frozen training MAP group.

Calibration run IDs/times must refer to the same training stimulus. Returns a separate ParticipantCalibration for independent new-run transforms; only its loadings, offsets and noise are optimized. Dense/grouped MAP without run baselines is supported. Units remain explicit; fit new-participant preprocessing on calibration data only.

BayesianMultimodalSRM.transform¶

BayesianMultimodalSRM.transform(
    data,
    *,
    times,
    modalities=None,
    data_layout="runs",
    readout="gp",
)

Infer each participant's held-out latent using only their observations.

Returns {subject: {run: GaussianMixtureSeries}} in the original training MAP coordinates. Parameters are fixed, including filters and preprocessing; no optimization or sampling occurs. Known participants and new run IDs are required. times is an explicit query vector or run-to-vector mapping. Observations retain their native clocks/masks.

modalities optionally selects a nonempty list before reading any excluded payload. Every supplied participant/run must retain input. Uncertainty is conditional on the training MAP. Independent estimates concern the same model latent; they do not introduce private factors.

readout="gp" uses the fitted temporal prior. "instantaneous" uses its unit-variance marginal prior and same-timestamp observations only: selected modalities must have Identity responses, white residual noise and no run baselines; spectral fits are unsupported. Only exact observed timestamps with at least one available feature are valid. Its uncertainty belongs to this instantaneous marginal model, not the full GP posterior. Neither readout refits or changes the trained model.

BayesianMultimodalSRM.sample_latent¶

BayesianMultimodalSRM.sample_latent(
    *,
    times,
    max_draws=200,
    draws_per_parameter=1,
    random_state=None,
    max_joint_size=2048,
)

Draw joint shared latent paths from an existing parameter posterior.

Returns one TrajectorySamples per run, with sample axes parameter draw / conditional draw / time / factor. All times and factors in a path are sampled jointly in that parameter draw's fitted reporting coordinates. No MAP search, MCMC or preprocessing is performed.

Supports dense/grouped Identity/Gaussian and quadrature Gamma/DoubleGamma/BatemanSCR posteriors with independent observation noise. max_draws balances retained draws across chains, as in infer_latent. random_state seeds NumPy's local generator; the model's sampling seed and state are unchanged. Increasing draws_per_parameter does not increase parameter ESS.

max_joint_size bounds query times times factors per run, since joint covariance storage and factorization scale quadratically and cubically in that size. Invalid times remain NaN, as in marginal queries. Separate calls/windows do not preserve cross-call correlation.

BayesianMultimodalSRM.infer_latent¶

BayesianMultimodalSRM.infer_latent(*, times, max_draws=200)

Common latent marginal mixtures in fitted reporting coordinates.

Multifactor posterior uses each draw's training-anchor QR rotation; MAP uses its fixed training rotation. Cross-factor covariance contributes to each projected variance; joint trajectory covariance is not returned.

BayesianMultimodalSRM.reported_parameter_draws¶

BayesianMultimodalSRM.reported_parameter_draws()

Read-only chain/draw/parameter copy with only loadings rotated.

Posterior rotations use the immutable fitted anchor keys. MAP retains its established training rotation; one factor retains raw coordinates. Fixed-parameter and sampler metadata always refer to raw coordinates.

BayesianMultimodalSRM.calibrate_posterior¶

BayesianMultimodalSRM.calibrate_posterior(
    data,
    *,
    search=None,
    sampler=None,
    random_state=None,
    progress=None,
)

Jointly sample group and one new participant's mapping parameters.

Calibration uses existing reference stimulus run IDs within their original domains. The returned posterior establishes an augmented reference while this estimator remains unchanged. Original reporting anchors are retained. This operation fits and samples; it does not establish calibration coverage.

BayesianMultimodalSRM.condition_participants¶

BayesianMultimodalSRM.condition_participants(
    data,
    *,
    sampler=None,
    random_state=None,
    progress=None,
)

Fit independent participant updates on distinct new stimulus run IDs.

Return a participant-to-posterior mapping. Each target combines the saved training/calibration reference with only that participant's current batch; previous new-run batches are replaced. All parameter uncertainty is sampled jointly, and no other participant's new observations enter that target. Existing MAP transform remains a fixed-parameter operation.