README.md

---
license: mit
library_name: dynvision
language:
  - en
tags:
  - neuroscience
  - vision
  - recurrent-neural-networks
  - pytorch
  - pytorch-lightning
  - dynamical-systems
  - computational-neuroscience
  - object-recognition
  - temporal-processing
  - imagenette
datasets:
  - imagenette
  - imagenet
  - cifar10
  - mnist
metrics:
  - accuracy
  - top-5-accuracy
  - reaction-time
model-index:
  - name: DyRCNN
    results: []
---

# DynVision — Trained Models and Evaluation Reports

This repository contains pre-trained model checkpoints and evaluation reports
from the [DynVision](https://github.com/Lindsay-Lab/DynVision) toolbox —
a modular framework for constructing and evaluating recurrent convolutional
neural networks (RCNNs) with biologically inspired temporal dynamics.

## Model Description

DynVision implements visual network architectures where neural activity evolves
according to continuous-time differential equations with realistic timescales.
Recurrent connections within and across processing stages allow the network to
integrate information over time, producing dynamics that can be aligned with
properties of biological visual systems.

### Architectures Included

| Architecture | Type | Description |
|-------------|------|-------------|
| **DyRCNNx8** | Recurrent | 8-layer dynamic RCNN with configurable recurrence types (full, self, depthwise, pointwise) and feedback/skip connections |
| **CorNet-RT** | Recurrent | CORnet model of the primate ventral visual stream with anatomically-inspired recurrent connections between areas V1, V2, V4, IT ([Kubilius et al., 2018](https://arxiv.org/abs/1909.06161)) |
| **CordsNet** | Recurrent | Scale-invariant contour integration with recurrent dynamics ([Soo et al., 2024](https://github.com/wmws2/cordsnet)) |

### Training

- **Framework**: PyTorch Lightning with Snakemake workflow management
- **Data loading**: FFCV for high-throughput image loading
- **Optimizer**: Adam with cosine annealing
- **Mixed precision**: Automatic (AMP)
- **Seeds**: 7000–7003
- **Datasets**: Imagenette, ImageNet, CIFAR-10, MNIST

### Evaluation Experiments

The reports directory contains evaluation results across multiple experimental
paradigms designed to probe temporal response properties:

  - **contrast**: 9 CSV files
  - **duration**: 9 CSV files
  - **gaussiannoise**: 16 CSV files
  - **gaussiannoiseffonly**: 11 CSV files
  - **hundred**: 5 CSV files
  - **interval**: 9 CSV files
  - **response**: 52 CSV files
  - **responseintermediate**: 12 CSV files
  - **stability**: 9 CSV files
  - **ten**: 4 CSV files

## Repository Contents

| Item | Count |
|------|-------|
| Model configs | 190 |
| Report files | 136 |
| Total size | 20005 MB |

```
models/
  {architecture}/
    {model_config}/
      {dataset}/
        trained-best.pt         # Best checkpoint weights
        trained.pt.config.yaml  # Training hyperparameters

reports/
  {experiment}/
    {model_config}/
      {data_group}/
        {run_hash}/
          test_data.csv         # Evaluation metrics
```

## Usage

### Loading a Pre-trained Model

```python
from huggingface_hub import hf_hub_download
from dynvision.utils.model_utils import load_model_and_weights

# Download a specific checkpoint
checkpoint_path = hf_hub_download(
    repo_id="neurograce/DynVision",
    filename="models/DyRCNNx8/DyRCNNx8:tsteps=20+dt=2+...+_7000/imagenette/trained-best.pt",
    repo_type="model",
)

# Load weights into the model architecture
model = load_model_and_weights(
    model_name="DyRCNNx8",
    weights_path=checkpoint_path,
)
```

### Accessing Evaluation Reports

```python
import pandas as pd
from huggingface_hub import hf_hub_download

# Download a report CSV
report_path = hf_hub_download(
    repo_id="neurograce/DynVision",
    filename="reports/contrast/DyRCNNx8:tsteps=20+...+_7000/imagenette:all_trained-best/test_data.csv",
    repo_type="model",
)

df = pd.read_csv(report_path)
print(df.head())
```

### Downloading the Full Model Directory

```python
from huggingface_hub import snapshot_download

# Download all files for offline use
local_path = snapshot_download(
    repo_id="neurograce/DynVision",
    repo_type="model",
    local_dir="./dynvision_models",
)
```

## Intended Uses

- Reproducing experimental results from the DynVision manuscript
- Benchmarking biologically-inspired recurrent architectures
- Studying temporal dynamics and response properties of visual networks
- Transfer learning and feature extraction with recurrence-augmented backbones

## Limitations

- Models were trained on specific image datasets (Imagenette, ImageNet, CIFAR-10,
  MNIST) and may not generalize to other domains without fine-tuning.
- Recurrent dynamics are sensitive to temporal parameters (τ, dt, t_recurrence);
  inference with different timestep configurations may produce unexpected behavior.
- Per-epoch checkpoints capture training trajectories but not all epochs are
  guaranteed to be stable minima.

## Citation

If you use these models or the DynVision toolbox in your research, please cite:

```bibtex
@article{gutzen2025dynvision,
  title={DynVision: A Modular Toolbox for Biologically Plausible Recurrent Visual Networks},
  author={Gutzen, Robin and others},
  journal={bioRxiv},
  year={2025},
  doi={10.1101/2025.08.11.669756}
}
```

## License

This repository is distributed under the [MIT License](https://github.com/Lindsay-Lab/DynVision/blob/main/LICENSE).