API: choose a model and its settings¶

Start here when you know what you want to estimate but are unsure which arguments to use. The linked reference pages list every public export, constructor default, and public method defined on those classes. These pages follow the checked-out source; the installed release may have fewer options.

The choices at a glance¶

Estimator signatures · Responses and priors · Search and sampling · Data and results · Evaluation

Data and units¶

from multimodalsrm import TimeSeries

# Each values array has shape (time, feature); times are strictly increasing.
data = {
    "participant-01": {
        "run-01": {
            "fmri": TimeSeries(values=fmri_values, times=fmri_times, mask=fmri_mask),
            "rating": TimeSeries(values=rating_values, times=rating_times),
        }
    }
}

The names and arrays above are illustrative. Use one consistent time unit, normally seconds. Modalities keep their native sampling times. A mask is Boolean, has the same shape as values, and marks observed entries with True. Omit fully missing streams. Feature counts may differ between participant–modality pairs but must stay fixed across runs for a given pair. See data preparation.

R-MSRM settings¶

Import MultimodalSRM from multimodalsrm. latent_dt is required. The estimator fits preprocessing on the training data and reuses it for predictions.

GP-MSRM settings¶

Import BayesianMultimodalSRM, BayesianPriors, and Prior from multimodalsrm.bayesian. The GP consumes supplied units without internal standardization. Set JAX_ENABLE_X64=true before starting Python/JAX for fitting.

Fixed- and learned-response state-space filtering and smoothing automatically group exactly matching modality/time observations when noise support is strictly positive. This is separate from selecting linear_algebra="grouped"; no new switch is needed. See grouped state-space computation.

Search and sampling¶

Exact defaults and signatures are generated from source.

SearchConfig(r_init=True) opts in to seeding the first MAP restart from a bounded R-MSRM fit; the default r_init=False keeps the historical start. See the GP-MSRM installation example.

A GP MAP configuration with a learned Gaussian lag¶

This creates a configuration; it does not fit data. Prior scales below are illustrative and must be chosen in the supplied measurement units.

from multimodalsrm import Gaussian, Identity, Response
from multimodalsrm.bayesian import BayesianMultimodalSRM, BayesianPriors, Prior

responses = {
    "rating": Response(Identity(), estimate=False, pooling="shared"),
    "fmri": Response(
        Gaussian(width=1.0, lag=2.0),
        pooling="shared",
        estimate=True,
        fixed={"width": 1.0},
        bounds={"lag": (0.0, 5.0)},
    ),
}
model = BayesianMultimodalSRM(
    features=1,
    inference="map",
    linear_algebra="grouped",
    responses=responses,
    length_scale=3.0,
    priors=BayesianPriors(
        noise=Prior.lognormal(-2.0, 0.7),
        loading_sd=1.0,
        offset_sd=1.0,
        filters={"fmri": {"lag": Prior.normal(2.0, 1.0)}},
    ),
)

The Response bounds truncate and renormalize the corresponding GP filter prior. See tutorials for runnable fits and temporal kernels for fixed, lag-only and shape-learning examples.

Methods: which operation do I need?¶

Full method signatures include progress, query and calibration options. Consult the capability guide before combining advanced options. A finite objective, narrow interval or successful call does not establish convergence or recovery.