RatInABox

RatInABox (see paper) is a toolkit for generating synthetic behaviour and neural data for spatially and/or velocity selective cell types in complex continuous environments.

With RatInABox you can:

• Generate realistic trajectories for rats exploring complex 1 and 2D environments under a smooth random policy, an external control signal, or your own trajectory data.

• Generate artificial neuronal data for various location- or velocity-selective cells found in the brain (e.g., but not limited to, Hippocampal cell types), or build your own more complex cell types.

• Build and train complex multi-layer networks of cells, powered by data generated with RatInABox.

RatInABox is an open source project welcoming contributions. If you use RatInABox please cite the paper and consider giving this repository a star ☆. It contains three classes:

1. Environment()📦: The environment/maze (or “box”) that the agent lives in. 1- or 2-dimensional.

2. Agent() 🐀: The agent (or “rat”) moving around the Environment.

3. Neurons() 🧠: A population of neurons with firing rates determined by the state (position and velocity) of the Agent. Make your own or use one of our premade cell types including:

   • PlaceCells()

   • GridCells()

   • BoundaryVectorCells() (egocentric or allocentric)

   • ObjectVectorCells()

   • VelocityCells()

   • SpeedCells()

   • FieldOfViewNeurons() (egocentric encoding of what the Agent can see)

   • RandomSpatialNeurons()

   • HeadDirectionCells()

   • FeedForwardLayer() (a generic class analagous to a feedforward layer in a deep neural network)

   • NeuralNetworkNeurons() (a generic class analagous to a deep neural network)

   • SuccessorFeatures()

   • …

The top animation shows an example use case: an Agent randomly explores a 2D Environment with a wall. Three populations of Neurons (PlaceCells, GridCells, BoundaryVectorCells) fire according to the receptive fields shown. All data is saved into the history for downstream use. RatInABox is fully continuous in space; this means that position and neural firing rates are calculated rapidly online with float precision rather than pre-calculated over a discretised mesh. RatInABox is flexibly discretised in time; dt can be set by the user (defaulting to 10 ms) depending on requirements.

Key features

• Non-specific: Trajectories can be randomly generated, imported, or adaptively controlled making RatInABox a powerful engine for many tasks involving continuous motion (e.g. control theory or reinforcement learning).

• Biological: Simulate large populations of spatially and/or velocity modulated cell types. Neurons can be rate based or spiking. The random motion model is fitted to match real rodent motion.

• Flexible: Simulate environments in 1D or 2D with arbitrarily wall, boundary and hole arrangements. Combine premade or bespoke Neurons classes into arbitrary deep networks (examples given).

• Fast: Simulating 1 minute of exploration in a 2D environment with 100 place cells (dt=10 ms) take just 2 seconds on a laptop (no GPU needed).

• Precise: No more prediscretised positions, tabular state spaces, or jerky movement policies. It’s all continuous.

• Easy: Sensible default parameters mean you can have realisitic simulation data to work with in <10 lines of code.

• Visual Plot or animate trajectories, firing rate timeseries’, spike rasters, receptive fields, heat maps, velocity histograms…using the plotting functions (summarised here).

Contribute

RatInABox is open source project and we actively encourage all contributions from example bug fixes to documentation or new cell types. Feel free to make a pull request (you will need to fork the repository first) or raise and issue.

We have a dedicated contribs directory where you can safely add awesome scripts and new Neurons classes etc.

Questions? Just ask! Ideally via opening an issue so others can see the answer too.

Thanks to all contributors so far:

Cite

If you use RatInABox in your research or educational material, please cite the work as follows: Bibtex:

@article{ratinabox2022,
	doi = {10.1101/2022.08.10.503541},
	url = {https://doi.org/10.1101%2F2022.08.10.503541},
	year = 2022,
	month = {aug},
	publisher = {Cold Spring Harbor Laboratory},
	author = {Tom M George and William de Cothi and Claudia Clopath and Kimberly Stachenfeld and Caswell Barry},
	title = {{RatInABox}: A toolkit for modelling locomotion and neuronal activity in continuous environments}
}

Formatted:

Tom M George, William de Cothi, Claudia Clopath, Kimberly Stachenfeld, Caswell Barry. "RatInABox: A toolkit for modelling locomotion and neuronal activity in continuous environments" (2022).

The research paper corresponding to the above citation can be found here.