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:
Environment()
📦: The environment/maze (or “box”) that the agent lives in. 1- or 2-dimensional.Agent()
🐀: The agent (or “rat”) moving around theEnvironment
.Neurons()
🧠: A population of neurons with firing rates determined by the state (position and velocity) of theAgent
. 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 theAgent
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.