Python and Google Colab

Overview

You can run RODENT experiments from a Python notebook in Google Colab instead of the website. There is no 3D view: runs are fast, and the results arrive as tables, charts and files you can analyse. Everything you create or save is shared with the website, so a run saved from Colab can be replayed in 3D under 3 Review.

You do not need to install anything on your computer or know much Python. The notebook does the work; you press Run.

What you need

• A Google account.
• Your RODENT website email and password.
• The link to the Getting started notebook, from your project lead.

One-time setup

1. Open the notebook link, then choose File > Save a copy in Drive. Work in your copy from now on.

2. Click the key icon in the left sidebar (Secrets) and add two secrets:

   Name	Value
   RODENT_EMAIL	your RODENT email
   RODENT_PASSWORD	your RODENT password

3. Switch on Notebook access for both.

Secrets keep your password out of the notebook itself, so the notebook is safe to share.

Running the notebook

Choose Runtime > Run all. If Colab warns that the notebook was not written by Google, choose Run anyway. The first run takes about a minute while the simulator downloads.

The notebook then:

1. signs you in and lists your projects;
2. opens the project and experiment you type in the boxes on the right (a new project is created if the name is new);
3. shows the setup: seed, regions, doors, stimuli and treatment;
4. applies any changes you switch on, and saves them to the website;
5. runs the experiment;
6. shows a trajectory plot and a table of time spent in each region; and
7. saves the run to the website and downloads a CSV file.

Changing the setup

Section 4 of the notebook contains example lines starting with #. Remove the # to use a line, then run the cell:

exp.doors["bridge_entry_gate"].open = False       # close a door
exp.stimuli["bridge_light"].intensity = 250        # dim a light to 250 lux
exp.treatment.condition = "placebo"                # no_treatment, placebo or medicine
exp.seed = 42

Door and stimulus names come from the setup printed in section 3. Your project role decides what you may change; anything else is refused with a message listing what you may change.

Changes during a run

Doors and stimuli can also change at chosen steps. They are recorded exactly like changes made on the website:

run = exp.run(steps=5000, changes={2500: {"doors": {"bridge_entry_gate": True}}})

One step is 0.1 seconds by default, so 5000 steps is 500 seconds of simulated time.

Understanding the results

Result	Meaning
time_s	Seconds spent in each region.
entries	How many times the rat entered each region.
first_entry_s	When it first entered each region.
Trajectory plot	The path in red. Doors are green when open and black when closed at the end; an orange border means the door changed during the run.
CSV file	One row per step: time, position, region, active stimuli and changes.

The same experiment and seed always give the same run, on any computer.

Rules to know

Situation	What happens
A change outside your role	Refused; the message lists what you may change.
Adding an experiment from a template	Project leads only. Others copy an existing experiment with exp.save_as_new("name").
Editing a published version	Refused. Continue with save_as_new.
A colleague saved after you loaded	Refused instead of overwriting their work. Reload and redo your change.
Saving a run made with unsaved changes	Refused, because the website replays runs on the saved arena. Save first, then run again.
Two projects with the same name	Refused; use the project's id from the list instead.

Coming back later

Colab clears its memory when a session ends. Open your copy from Google Drive (Colab Notebooks folder) and choose Runtime > Run all again. Your secrets are kept.

More

• The full researcher manual and a command cheat sheet are available from your project lead.
• Developers: see Python SDK and Headless API (Huzaifa).