Concepts & Architecture

braincoder wraps common steps in the encoding/decoding workflow for fMRI analysis. The package is split into small, composable modules so you can swap out only the parts you need or script full experimental pipelines.

Core pipeline

  1. Describe the paradigm. Provide stimulus traces for each time point as a pandas DataFrame. Stimulus helpers in braincoder.stimuli clean the paradigm and generate design matrices tailored to the selected model.

  2. Choose an encoding model. Classes in braincoder.models turn the paradigm into voxel-wise predictions. EncodingModel handles formatting plus utilities such as simulation, gradients, and conversion to discrete grids.

  3. Model the hemodynamic response. Attach an HRFModel or use SPMHRFModel to convolve predicted activity with a canonical or voxel-specific HRF.

  4. Fit parameters or weights. braincoder.optimize.WeightFitter solves linear weights via least squares, whereas braincoder.optimize.ParameterFitter runs iterative TensorFlow optimizers with support for constraints, shared parameters, and progress logging.

  5. Decode or visualize. Use the fitted encoding model to simulate responses, compute gradients, or invert the model (see the tutorials and example notebooks in docs/tutorial and notebooks).

Stimulus paradigms

Stimulus classes (see braincoder.stimuli) encapsulate domain knowledge about the feature space. When you pass a paradigm to an encoding model it automatically routes through the matching Stimulus subclass to:

  • ensure required columns/dimensions are present,

  • optionally clean and normalize user input, and

  • generate tensors that the TensorFlow models expect.

Encoding models

All encoding models derive from braincoder.models.EncodingModel, which provides:

  • predict and simulate helpers that work with numpy/pandas inputs,

  • automatic broadcasting to batches/voxels, and

  • convenience methods to fetch paradigms, parameters, and gradients.

Common subclasses include LinearModel, LinearModelWithBaseline, and HRF-aware versions such as LinearModelWithBaselineHRF. Because they share the base API you can swap them without rewriting fitting code.

Hemodynamic response functions

braincoder.hrf implements standalone HRF utilities and the SPMHRFModel. You can:

Optimization, fitting, and decoding

Use braincoder.optimize.WeightFitter for fast linear weight solves or braincoder.optimize.ParameterFitter when you need to estimate model parameters themselves. Both accept pandas inputs, work with TensorFlow accelerators, and expose diagnostics such as R² traces and intermediate parameter snapshots.

Where to go next