RatInABox <img align="right" src=".images/readme/logo.png" width=150>

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.

Install | Demos | Features | Contributions and Questions | Cite

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.

<img src=".images/readme/ratinabox.gif" width=850>

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).

<!-- ## Announcement about support for OpenAI's `gymnasium` <img src=".images/readme/gymnasium_logo.svg" width=25> API A new wrapper contributed by [@SynapticSage](https://github.com/SynapticSage) allows `RatInABox` to natively support OpenAI's [`gymnasium`](https://gymnasium.farama.org) API for standardised and multiagent reinforment learning. This can be used to flexibly integrate `RatInABox` with other RL libraries such as Stable-Baselines3 etc. and to build non-trivial tasks with objectives and time dependent rewards. Check it out [here](https://github.com/RatInABox-Lab/RatInABox/blob/main/ratinabox/contribs/TaskEnv_example_files/TaskEnvironment_basics.md). -->

Get started

Many demos are provided. Reading through the example scripts (one simple and one extensive, duplicated at the bottom of the readme) these should be enough to get started. We also provide numerous interactive jupyter scripts as more in-depth case studies; for example one where RatInABox is used for reinforcement learning, another for neural decoding of position from firing rate. Jupyter scripts reproducing all figures in the paper and readme are also provided. All demos can be run on Google Colab

Installing and Importing

Requirements are minimal (python3, numpy, scipy and matplotlib, listed in setup.cfg) and will be installed automatically.

Install the latest, stable version using pip at the command line with

$ pip install ratinabox

Alternatively, in particular if you would like to develop RatInABox code or if you want the bleeding edge (may occasioanlly break), install from this repo using

$ git clone --depth 1 https://github.com/RatInABox-Lab/RatInABox.git
$ cd RatInABox
$ pip install -e .

n.b. the "editable" -e handle means changes made to your clone will be reflected when you next import RatInABox into your code.

Import into your python project with

import ratinabox
from ratinabox.Environment import Environment
from ratinabox.Agent import Agent
from ratinabox.Neurons import PlaceCells, GridCells #...

Feature run-down

Here is a list of features loosely organised into those pertaining to

(i) the Environment

• Adding walls
• Complex Environments: Polygons, curves and holes
• Objects
• Boundary conditions
• 1- or 2-dimensions

(ii) the Agent

• Random motion
• Importing trajectories
• Policy control
• Wall repelling
• Multiple Agents
• Advanced Agent classes

(iii) the Neurons.

• Cell types
• Noise
• Spikes vs rates
• Plotting rate maps
• Place cell models
• Place cell geometry
• Grid cell models
• Egocentric encodings
• Reinforcement learning and successor features
• Deep neural networks
• Create your own Neuron types

(iv) Figures and animations plotting

Specific details can be found in the paper.

(i) Environment features

Walls

Arbitrarily add walls to the environment to produce arbitrarily complex mazes:

Environment.add_wall([[x0,y0],[x1,y1]])

Here are some easy to make examples.

<img src=".images/readme/walls.png" width=1000>

Complex Environments: Polygons, curves, and holes

By default, Environments in RatInABox are square (or rectangular if aspect != 1). It is possible to create arbitrary environment shapes using the "boundary" parameter at initialisation.

You can also add holes to the Environment using the "holes" parameter at initialisation. When sampling positions from the Environment (e.g. at initialisation), holes won't be included.

Any curved environments can be made by creating a boundary of many small walls (use sparingly, walls may slow down computations, particular for wall-responsive representations, e.g. boundary vector cells.)

#A trapezium shaped Environment
Env = Environment(params={
    'boundary':[[0,-0.2],[0,0.2],[1.5,0.5],[1.5,-0.5]],
    })

#An environment with two holes making a figure of 8
Env = Environment(params={
    'aspect':1.8,
    'holes' : [[[0.2,0.2],[0.8,0.2],[0.8,0.8],[0.2,0.8]],
               [[1,0.2],[1.6,0.2],[1.6,0.8],[1,0.8]]],
    })

#A circular environment made from many small walls
Env = Environment(params = {
    'boundary':[[0.5*np.cos(t),0.5*np.sin(t)] for t in np.linspace(0,2*np.pi,100)],
    })

<img src=".images/readme/complex_envs.png" width=1000>

Objects

Environments can contain objects. These are used by ObjectVectorCells as visual cues but in theory you can hijack th