API Reference

This section documents the most frequently used modules. All classes operate on numpy arrays or pandas DataFrame inputs and run TensorFlow under the hood.

Encoding models

class braincoder.models.EncodingModel(paradigm=None, data=None, parameters=None, weights=None, omega=None, verbosity=20)

Bases: object

Abstract base class for encoding models.

get_paradigm(paradigm)

Return the cleaned paradigm DataFrame, falling back to stored one.

get_parameter_labels()

Return the ordered list of parameter labels used by the model.

predict(paradigm=None, parameters=None, weights=None)

Return pandas predictions for the provided paradigm/parameters.

simulate(paradigm=None, parameters=None, weights=None, noise=1.0, dof=None, n_repeats=1)

Generate synthetic data by adding noise to predictions.

class braincoder.models.LinearModelWithBaseline(paradigm=None, data=None, parameters=None, weights=None, omega=None, verbosity=20)

Bases: EncodingModel

Linear encoding model that adds a voxel-specific baseline parameter.

class braincoder.models.LinearModelWithBaselineHRF(paradigm=None, data=None, parameters=None, weights=None, hrf_model=None, verbosity=20, **kwargs)

Bases: LinearModelWithBaseline, HRFEncodingModel

LinearModelWithBaseline variant that automatically applies an HRF convolution.

HRF utilities

class braincoder.hrf.HRFModel(unique_hrfs=False)

Bases: object

Base class that handles HRF generation and convolution with predictions.

class braincoder.hrf.SPMHRFModel(tr, unique_hrfs=False, highres_dt=0.1, time_length=32.0, onset=0.0, delay=6.0, undershoot=16.0, dispersion=1.0, u_dispersion=1.0, ratio=0.167, min_hrf_delay=3.0, max_hrf_delay=7.0, min_dispersion=0.3, max_dispersion=2.0)

Bases: HRFModel

Canonical SPM-style HRF parameterized by delay/dispersion bounds.

braincoder.hrf.spm_hrf(t, a1=6.0, d1=1.0, a2=16.0, d2=1.0, c=0.16666666666666666, highres_dt=0.1)

Compute SPM canonical HRF(s).

Optimization helpers

class braincoder.optimize.WeightFitter(model, parameters, data, paradigm)

Bases: object

Closed-form solver for voxel weights given fixed parameters.

Uses least-squares to compute weights that best map basis predictions to measured data, optionally with L2 regularization via alpha.

fit(alpha=0.0)

Solve for weights using least squares with optional L2 regularization.

class braincoder.optimize.ParameterFitter(model, data, paradigm, memory_limit=666666666, log_dir=False)

Bases: object

Iterative optimizer that estimates model parameters for each voxel.

Single trainable (n_voxels, n_pars) keras Variable; only the masked positions (meaningful voxels × non-fixed params) receive gradients. Shared parameters are realized by a smaller Variable that’s broadcast back across voxels via a selector matrix.

Parameters:

  • model (EncodingModel)

  • data (pd.DataFrame) – Timeseries, shape (n_timepoints, n_voxels).

  • paradigm (array-like) – Stimulus paradigm; passed through model.get_paradigm.

  • memory_limit (int) – Soft budget for the grid-fit chunk size.

  • log_dir (str | None | False) – TensorBoard log dir. False (default) disables logging.

fit(max_n_iterations=1000, min_n_iterations=100, init_pars=None, confounds=None, optimizer=None, fixed_pars=None, shared_pars=None, noise_model='ssq', store_intermediate_parameters=False, r2_atol=1e-06, lag=100, learning_rate=0.01, progressbar=True, **kwargs)

Estimate per-voxel parameters by iterative optimization.

Parameters:

  • noise_model ({‘ssq’, ‘gaussian’}, default 'ssq') – Loss function. 'ssq' minimizes the unweighted sum-of-squared-residuals (MLE under homoscedastic Gaussian noise). 'gaussian' minimizes a per-voxel Gaussian negative log-likelihood with a free per-voxel σ²ᵥ; the θ-gradient is auto-rescaled by per-voxel noise, which under a shared Adam optimizer gives every voxel comparable per-iteration progress. Same fixed points as 'ssq', but much faster convergence in practice on real fMRI (heteroskedastic noise). When set, self.estimated_sigma2 holds the fitted per-voxel σ² after fit() returns.

  • fixed_pars (list[str] | None) – Parameter names to hold at their init value (fixed_pars) or to tie to a single shared value across voxels (shared_pars).

  • shared_pars (list[str] | None) – Parameter names to hold at their init value (fixed_pars) or to tie to a single shared value across voxels (shared_pars).

  • r2_atol (float, int, int) – Early-stop: stop when R² has improved by less than r2_atol over the last lag steps, after min_n_iterations.

  • lag (float, int, int) – Early-stop: stop when R² has improved by less than r2_atol over the last lag steps, after min_n_iterations.

  • min_n_iterations (float, int, int) – Early-stop: stop when R² has improved by less than r2_atol over the last lag steps, after min_n_iterations.

  • **kwargs – Forwarded to keras.optimizers.Adam when optimizer is None.

Returns:

Per-voxel parameter estimates, indexed by voxel.

Return type:

pd.DataFrame