CORread: training models of the visual cortex to read

The research

When people learn to read, part of the brain's object recognition system takes on a new job. A patch of the ventral occipitotemporal cortex, the visual word form area, becomes selective for written words. Hannagan et al. (2021) reproduced this "neuronal recycling" in CORnet-Z, a convolutional network modeled on the ventral visual stream. They trained the network first on images and then on images and words together, and a small set of its units became selective for words, with a code for letters and their positions. In the summer of 2026 I joined a group of two professors and a postdoc at the Universitat de València who build on this work to compare CORnet networks with the human ventral occipitotemporal cortex. I found their experiments and their scientific vision fascinating, and working on them taught me a field I hadn't studied before. CORread is the software side of my senior thesis. The version on GitHub is the published core, and I keep testing new experiments in a private repository before they move into the library. AI usage disclosure: Claude Code was used to assist with the implementation of CORread and the writing of its documentation. An LLM also helped me adapt the README and documentation into this page.

Why I built a library

The group's code had grown the way research code often does. Each new experiment started from a working copy of the one before, which let the team test ideas quickly and follow the science where it led. Over time that left several versions of similar scripts, each tuned for a different experiment and set up for the machines it ran on. As a newcomer, I found a few things hard: finding where a given experiment lived, getting the code to run on a different machine, and tracing a number back to the run that produced it. A single training run can take days on a GPU, so a run that can't be found or repeated is costly to lose. These experiments deserved to be easy to run, share and repeat, and I wanted the group to be able to keep building on them after my internship ended. So I turned the training code into a library with one tested implementation of each experiment.

What CORread does

CORread generates the word stimuli, trains pre-literate, illiterate and literate CORnet-Z and CORnet-S networks, measures how word-selective each unit of their last layer is, and lesions word-selective units to study how reading recovers. Each part of the design answers one of the problems above.

It installs with pip, and a single paths.toml says where the fonts, wordlists, ImageNet and models live on each machine. Moving to another machine only means editing that file.
Each run writes a metadata.json with its arguments, seed, the hashes of its data, the code version and the environment, along with the validation of the starting weights and of every epoch. Any number in a figure can be traced to the run and data behind it.
A word set is drawn from one seed and saved as a recipe, from which the same images can be regenerated byte for byte. Drawing a million word images again takes about a minute on 24 cores, compared with downloading about 9 GB.
Ctrl+C stops a run cleanly, and resume=True continues from the last checkpoint. One call trains a whole family of models (pre-literate, illiterate, and literate with and without the bias) and skips any that are already trained.
Trained models and word set recipes can be exported to a Hugging Face organization. Each model's card links it to the model it started from and the data it was trained on, so the group can download a finished model instead of training it again.
The library has a test suite, continuous integration and a documentation site.

Anyone with ImageNet, a wordlist and a few fonts can install CORread, train the same networks, and build new experiments on top of them.

Following runs live

Training runs last days, often on a lab machine that nobody is watching. CORread can send the status of each run to a web API: its progress, the validation after every epoch, and the error if one ends the run. Reports go out from a background thread, so a slow or unreachable server never holds up training. The library ships only the client, with the API contract documented as a JSON Schema, so any group can point it at a server of its own. I built a dashboard on that contract for our runs. It lists running, finished and failed runs, shows the progress and training curves of each one, and can compare all the models trained from the same pre-literate network.

The code it builds on

CORread comes from a line of code in which each step adapted the one before. CORnet, from the DiCarlo Lab at MIT, provides the CORnet-Z and CORnet-S architectures. Origins-of-VWFA, by Hannagan, Agrawal, Cohen and Dehaene, introduced the literacy training paradigm and the biased and unbiased readouts. The València group's adaptation of that code is what I developed the library from. All three are GPL-3.0, and so is CORread. The repository's NOTICE file lists which files derive from which source. Word stimuli and training are stable. Lesions currently work for CORnet-Z only, and sharing and status reports are still in beta, so some interfaces may change before version 1.0. Code and documentation: github.com/vk4444/CORread

CORread: training models of the visual cortex to read

The research

Why I built a library

What CORread does

Following runs live

The code it builds on

Related projects

Do soft words fall at the end of the sentence?

Web for Change: websites on a pay-what-you-can basis