🧬 biology

LITcoder: A General-Purpose Library for Building and Comparing Encoding Models

LITcoder is an open-source, modular library designed to streamline the development, benchmarking, and systematic comparison of neural encoding models by providing standardized tools for aligning continuous stimuli with brain data, while offering practical insights into critical methodological choices for continuous fMRI analysis.

Original authors: Taha Binhuraib, Ruimin Gao, Anna A. Ivanova

Published 2026-05-05

📖 5 min read🧠 Deep dive

CC BY 4.0

Original authors: Taha Binhuraib, Ruimin Gao, Anna A. Ivanova

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ⚕️ This is an AI-generated explanation of a preprint that has not been peer-reviewed. It is not medical advice. Do not make health decisions based on this content. Read full disclaimer

Imagine trying to understand how the human brain works by listening to a story. Scientists have long wanted to build a "decoder" that can predict exactly what your brain is thinking just by knowing what story you are hearing. This is called an encoding model.

However, building these models has been like trying to bake a cake where every chef uses a different oven, a different measuring cup, and a different recipe. One group measures ingredients in cups, another in grams; one bakes at 350°F, another at 400°F. Because of this, it's been nearly impossible to compare their results or know who actually baked the best cake.

Enter LITcoder. Think of LITcoder as a universal, open-source kitchen for brain scientists. It provides a standardized set of tools, ovens, and measuring cups so that anyone can bake a "brain prediction cake" and compare it fairly with anyone else's.

Here is how LITcoder works, using simple analogies:

1. The Assembly Line (Data Preparation)

First, you have two very different things: the story (text or audio) and the brain scan (fMRI data).

The Problem: Stories happen fast (words per second), but brain scans happen slowly (one "snapshot" every 2 seconds). It's like trying to match a high-speed race car video with a photo taken once every minute.
The LITcoder Solution: It uses a module called the AssemblyGenerator to line up the story and the brain scan perfectly in time. It then uses a Downsampler to figure out how to combine the fast words into the slow brain snapshots.
- Analogy: Imagine you are trying to describe a movie to someone who only sees one frame every 10 seconds. Do you just show them the last frame before the cut? Or do you average out the whole 10 seconds? LITcoder lets researchers test different ways to do this (like "averaging" the words vs. just picking the "last word") to see which method tells the truest story.

2. The Translator (Feature Extraction)

Once the data is lined up, the computer needs to turn the story into a language the brain model understands.

The LITcoder Solution: It uses a FeatureExtractor. This can be a simple translator (counting how many words are spoken per minute) or a super-smart translator (using advanced AI like GPT-2 or Whisper to understand the meaning of the words).
Analogy: Think of this as translating a book into different dialects. One dialect is "Word Count," another is "Simple Meaning," and another is "Deep AI Understanding." LITcoder lets scientists swap these translators instantly to see which one helps predict brain activity best.

3. The Time Machine (Hemodynamic Lag)

There is a tricky delay in the brain. When you hear a word, your brain doesn't light up instantly; it takes a few seconds for the blood flow to react (like a slow-motion light switch).

The LITcoder Solution: It uses a tool called FIR (Finite Impulse Response). Instead of assuming the brain reacts instantly, it looks at the current word and the words from the last few seconds to predict the brain's reaction.
Analogy: If you shout "Fire!" in a crowded room, the reaction isn't instant. People look around, then gasp, then run. LITcoder accounts for this "delayed reaction" so the model doesn't get confused about when the brain is actually responding.

4. The Fair Judge (Evaluation & Safety)

The biggest danger in these experiments is "cheating" by accident. If you train your model on a story and then test it on a part of the story that is right next to it, the model might just be memorizing the pattern of time rather than actually understanding the story.

The LITcoder Solution: It forces researchers to use strict Cross-Validation rules. It ensures the "training" data and "testing" data are separated by enough time so the model can't cheat.
Analogy: Imagine a student taking a test. If the teacher gives them the answers to the test during the study session, they will get a perfect score, but they haven't actually learned anything. LITcoder makes sure the "test" is a completely different chapter of the story, ensuring the model is actually smart, not just lucky.

What Did They Find?

Using this new kitchen, the authors tested three different story datasets (like The Little Prince and various audio stories) and found some important things:

Don't just pick the last word: When matching fast words to slow brain scans, looking at all the words in a time window works better than just picking the very last one.
Time matters: You need to account for that 2-3 second delay in the brain's reaction. Ignoring it makes the model less accurate.
Don't let the data cheat: If you mix up the order of the story when testing, the model looks way better than it really is. LITcoder helps prevent this "illusion" of success.
Head movement is the enemy: If a person moves their head too much during the scan, the model gets confused and performs poorly. LITcoder helps scientists spot and filter out these "wiggly" participants.

The Bottom Line

LITcoder isn't a magic pill that cures diseases or reads minds directly. Instead, it is a toolkit for building better, fairer, and more reliable experiments. It stops scientists from reinventing the wheel every time they want to study the brain, allowing them to focus on the real science: understanding how our brains process the stories we hear.

Technical Summary: LITcoder

Problem Statement

The field of neural encoding models, particularly those predicting brain responses to continuous stimuli like language, has experienced rapid growth but suffers from significant methodological heterogeneity. Different research groups employ disparate design choices regarding feature extraction, temporal alignment, downsampling strategies, and cross-validation protocols. This lack of standardized infrastructure complicates replication, hinders cross-paper comparisons, and introduces systematic biases (e.g., temporal autocorrelation inflating performance) that are difficult to control without principled pipelines. While frameworks like Brain-Score offer standardization, they often fix design choices, limiting the flexibility required to experiment with diverse encoding model configurations.

Methodology

The authors introduce LITcoder, an open-source, modular backend library designed to standardize the construction and benchmarking of neural encoding models while maintaining flexibility. The library implements a four-stage pipeline:

Data Preparation and Assembly: The AssemblyGenerator module ingests BIDS-formatted fMRI data, stimulus transcripts, and timestamps. It aligns brain data (volume or surface space) with stimuli to produce time-locked brain-stimulus pairs. It supports various anatomical masks (e.g., Glasser atlas, LanA language network) and context window strategies (full, half, or reset context).
Feature Extraction: The FeatureExtractor module transforms stimuli into representational features. It supports a wide range of sources, including pretrained language models (e.g., GPT-2, Pythia), speech models (e.g., Whisper, HuBERT), static embeddings (GloVe, word2vec), and low-level baselines (e.g., word rate). New extractors can be added by inheriting from a base class.
Downsampling to Neural Data: The Downsampler addresses the temporal mismatch between high-frequency token activations (e.g., ~3–4 tokens/s) and slow fMRI sampling (TRs of 1.5–2s). It implements multiple pooling and filtering strategies, including sum pooling, average pooling, last-token selection, and Lanczos filtering, to aggregate features into TR-sized windows.
Brain Response Prediction and Evaluation: The Mapping module performs voxel- or vertex-wise ridge regression. It incorporates Finite Impulse Response (FIR) modeling to account for hemodynamic lag by expanding feature vectors with $k$ lagged copies. It supports flexible cross-validation schemes (standard k-fold, contiguous folds, and contiguous folds with boundary trimming) to mitigate temporal leakage. The FIRExpander class specifically handles the construction of delayed feature matrices.

The library includes a Logger for system-wide monitoring, integrating with backends like Weights & Biases (W&B), TensorBoard, and CSV/JSON, and supports execution on local, HPC, and SLURM environments.

Key Contributions

Modular Infrastructure: LITcoder provides a unified, extensible backend that decouples core pipeline components (alignment, extraction, downsampling, mapping) from front-end interfaces, allowing researchers to swap design choices without rewriting infrastructure.
Standardized Methodological Controls: The library enforces best practices for critical methodological choices, such as accounting for all tokens within a TR (rather than just the last one), modeling hemodynamic lag via FIR, and using train-test splits that minimize information leakage (e.g., contiguous folds with boundary trimming).
Systematic Comparison: By unifying the pipeline, LITcoder enables direct, apples-to-apples comparisons across different datasets, feature families, and methodological configurations.

Experimental Results

The authors evaluated LITcoder using three naturalistic story-listening fMRI datasets: LeBel, Narratives, and Little Prince.

Feature Families: Language models (GPT-2, Pythia) consistently outperformed static embeddings, speech models, and word-rate baselines in predicting neural responses within the language network. Predictivity scaled with model size (e.g., larger Pythia models yielded higher scores).
Downsampling and Temporal Modeling: Aggregation strategies that incorporated all tokens within a TR window (sum/average pooling, Lanczos filtering) yielded higher predictivity than "last-token" selection. FIR modeling improved performance up to a dataset-specific plateau (approx. 9–12 seconds for TR=2.0s), after which returns diminished.
Cross-Validation Strategy: Experiments demonstrated that shuffled (randomized) cross-validation folds artificially inflated predictivity scores due to temporal leakage. Contiguous folds provided more conservative benchmarks, and adding boundary trimming further mitigated leakage from neighboring samples.
Head Motion: A consistent negative correlation was observed between head motion (mean framewise displacement) and encoding model predictivity across all datasets, indicating that motion accounts for a meaningful fraction of between-subject variance.

Significance and Claims

The paper claims that LITcoder lowers technical barriers to implementing encoding models and facilitates systematic, reproducible comparisons across models and datasets. By providing a flexible yet rigorous framework, it aims to foster methodological rigor in the field. The authors emphasize that the library does not merely automate existing workflows but highlights the critical importance of specific design choices—such as proper temporal alignment, hemodynamic lag modeling, and motion control—that significantly impact reported predictivity. The tool is positioned as a complement to standardized benchmarks like Brain-Score, offering the flexibility needed to explore the vast design space of encoding models while ensuring transparency and reproducibility.