Update model card

README.md

@@ -0,0 +1,188 @@
+---
+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 |
+| **CordsNet** | Feedforward | Scale-invariant contour integration network with pretrained weights |
+
+### 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-epoch=N.pt      # Per-epoch checkpoints
+        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).