The Problem

Researchers need a reproducible pipeline to test how biological constraints (sparsity, spiking thresholds, recurrence) affect the geometry of spatial representations learned from egocentric sensory streams. Existing code bases often mix training, evaluation, and data‑generation scripts, making systematic experimentation difficult.

What This Does

The repository implements a full experimental loop for the EM‑NAV study.

  • Training – train.py builds a spiking‑recurrent network (defined in models.py) and runs deep‑RL episodes that feed egocentric ray‑cast inputs (wrappers/raycast.py). Model weights are saved as .pt files under checkpoints/ (e.g., agent_A_task1_seed_42.pt).
  • Evaluation – Three scripts (evaluate_decision_gate.py, evaluate_representations.py, evaluate_single_units.py) load a checkpoint, run the agent in a fixed maze, and compute linear decodability, decision‑gate performance, and single‑unit analyses.
  • Auxiliary tools – kaggle_train_all.py provides a batch‑run wrapper for the Kaggle environment, while stage_zero_scan.py runs a quick sanity‑check of the environment and network initialization. The Jupyter notebook check.ipynb demonstrates a minimal end‑to‑end run.

Documentation files (README.md, OVERVIEW.md, Docs/*.md) describe the scientific motivation and list the core hypotheses but do not contain step‑by‑step usage instructions.

How It Is Wired

FilePrimary RoleKey Functions / Calls
train.pyEntry point for model trainingimports models.Network, wrappers.raycast.RayCastEnv; constructs Network(**config), runs env.reset() → env.step(action) loop; saves checkpoint via torch.save.
models.pyDefines the spiking‑recurrent architectureNetwork.__init__ builds torch.nn layers, registers spiking thresholds; Network.forward processes ray‑cast vectors, returns action logits.
wrappers/raycast.pyProvides egocentric sensory inputRayCastEnv.reset, RayCastEnv.step perform ray‑casting in a 2‑D arena (uses blender/continuous_eval.py for geometry).
evaluate_*.py (three files)Load checkpoint, run inference, compute metricsEach imports torch, models.Network, wrappers.raycast.RayCastEnv; calls torch.load(checkpoint_path), runs a fixed‑length episode, then calls metric functions (compute_decodability, compute_rsa, etc.) defined locally.
kaggle_train_all.pyBatch driver for multiple seeds/tasksLoops over seed/task combos, invokes subprocess.run(["python","train.py",...]).
stage_zero_scan.pyQuick sanity checkInstantiates RayCastEnv, runs a single forward pass through an untrained Network.
blender/continuous_eval.pyGeometry helper used by RayCastEnvSupplies mesh‑based distance queries; called from RayCastEnv._sample_rays.
check.ipynbDemonstrative notebookExecutes the same flow as train.py/evaluate_*.py but inline for inspection.

Control flow: execution starts at train.py (or any evaluate_*.py). The script constructs a Network (from models.py), wraps the environment (RayCastEnv), runs the RL loop, and writes a checkpoint. Evaluation scripts load that checkpoint, re‑instantiate the same Network, and run inference through the same environment to compute metrics. The only external I/O is reading/writing .pt files in checkpoints/ and writing metric logs (currently printed to stdout). No database or network services are used.

The most connected module is models.py; any change to layer definitions propagates to both training and all evaluation scripts. wrappers/raycast.py is the second hub because every script depends on the same sensory interface. No cyclic imports are present, but the tight coupling means that altering the input dimensionality requires coordinated updates in models.Network and the metric code.

How To Use It

# 1. Clone the repository
git clone https://github.com/moses-y/em-nav-representation-geometry
cd em-nav-representation-geometry

# 2. Install Python dependencies (Python 3.10+ required)
pip install -r requirements.txt

# 3. Train a model (example: agent A, task 1, seed 42)
python train.py --agent A --task 1 --seed 42

# 4. Evaluate the trained checkpoint
python evaluate_representations.py --checkpoint checkpoints/agent_A_task1_seed_42.pt

The --agent, --task, and --seed flags are inferred from the naming pattern used for checkpoint files; the scripts parse them with argparse (verified in the source).

If you need to run the full batch used in the paper:

python kaggle_train_all.py

The repository does not provide a configuration file; all hyper‑parameters are hard‑coded or passed via command‑line flags inside the scripts. The Docs/ folder contains the research proposal and progress logs but no runtime instructions.

Real‑World Use

A lab could integrate this code into a larger simulation platform by importing models.Network and wrappers.raycast.RayCastEnv:

from models import Network
from wrappers.raycast import RayCastEnv
import torch

net = Network(sparsity=0.02, recurrent=True)
env = RayCastEnv(map_id='arena_01')
obs = env.reset()
action = net(torch.from_numpy(obs).float())

The returned action can be fed back to the environment for closed‑loop experiments or for probing representation geometry with custom analyses.

Code Health & Issues

  • Medium – No CI/CD pipeline – No .github/, tox.ini, or Makefile present.
  • Low – Unpinned dependencies – Only requirements.txt exists; no requirements-lock.txt or pipfile.lock.
  • Low – Sparse test coverage – Single test file test_init.py does not exercise training or evaluation paths.
  • Low – Large checkpoint bloat – 24 .pt files (~hundreds of MB) are stored in the repo, inflating clone size.
  • Low – Missing usage docs – README explains scientific goals but lacks concrete run commands; users must infer from script names.

No security‑sensitive secrets are committed, and the MIT license is present.

The Bottom Line

The repo delivers a coherent, script‑driven pipeline for training and evaluating spiking‑recurrent navigation agents, with clear entry points and a minimal external footprint. However, the lack of automated testing, pinned dependencies, and explicit usage documentation raises reproducibility concerns. It is suitable for researchers comfortable navigating a code base with modest engineering scaffolding and who can extend the existing scripts to fit their own experimental protocols.