Quickstart

TipWelcome!

This page will walk you through everything you need to run, create, and analyse a freely-walking experiment. If you are new to this setup, read through this page first, then follow the links to the detailed pages as needed. For hardware and software requirements, see the Rig Specs page.

NoteFirst time here?

If you haven’t set up the system yet, start with the Installation & Setup page for software dependencies and configuration steps.

---

How to run a protocol

Fly prep and hardware:

• 45-60 minutes before starting, turn the red switch on the heating board at the top of the box on to pre-warm the chamber. This ceramic heating unit is plugged into a thermostat (temp sensor is located above the arena near the camera) and stabilizes the temperature at 28deg celsius (+/- 0.5deg)
• Fill an ice bucket in preparation for anesthetizing flies for loading into the arena.
• Retrieve a vial of 15 sorted flies. Move the flies into the small tube vial and place the vial into the ice.
• Make sure the acquisition computer is on and connected to the LED arena, and that the processing computer is on and connected to the network drive.
• Turn on the LED arena and the power supply for the heat ring by turning on the multi-socket at the back of the cabinet. The arena should light up with a test pattern when it is powered on. This multi-socket also turns on a small fan that is inside the cabinet which can be turned on between experiments if needed.
• Press the ‘Output ON/OFF’ button on the heat ring’s power supply and twist the dial til the display reads 20V. During drier periods of the year, this can be reduced to 18-19V to prevent overheating.
• Turn the arena controller on by flipping the switch on the front of the controller box. The controller box is the black box on the shelf outside of the cabinet.

Software prep:

• Open the BIAS (SimpleBiasCameraInterface) software on the acquisition computer — ensure the IR illumination is on and the camera is acquiring at 30 fps.
• Open PControl in MATLAB and verify it connects to the LED panels.
• Open the camera software on the processing computer. This is linked up to a small webcam camera that relays a live stream view of the arena in visible light (while the main camera records in IR). This is useful for monitoring the flies throughout the experiment.
• Make sure that the freely-walking-optomotor GitHub repo is added to the path in MATLAB.

Configure the computer paths:

Please refer to the page on computer configuration for detailed help on the below steps.

• Make sure that the path cfg.project_root has been set for your specific computer within the get_config.m file. This is the top level folder of where the data will be stored.
• If you are setting up either the acquisition or processing computer set the computer name.

Putting the flies in the arena:

• Once cooled, load the flies into the arena, place the glass plate on top of the flies making sure that the sigmacote-d side is face down.
• Count the number of flies now while they are still anesthetized, this will be entered in the parameters drop down when starting the experiment.
• Close the cabinet door.
• Wait for 5 minutes.

Running the experiment:

• Open the MATLAB script for the protocol you want to run (e.g. protocol_27.m).
• Press ‘Run’ to start the MATLAB protocol script. A MATLAB pop-up window should appear where the user should select the input parameters for the experiment. Once the parameters are selected, the script will begin executing. You should see that the BIAS software has started acquiring frames and the experiment progress will be printed in the MATLAB command window. The stimulus will start after the initial acclimation period (typically 5 minutes) and the flies will be recorded throughout.

After the protocol finishes, the data folder is transferred to the processing computer and runs FlyTracker to generate tracking output. The MATLAB processing pipeline then generates results files and figures, which are saved on the network drive and local archive. You can monitor the progress of all experiments via the pipeline status page.

TipHaving trouble?

This page covers common problems and their solutions, organised by the stage at which they occur.

How to make a protocol

The easiest way to create a new protocol is to start from the protocol template (src/protocols/protocol_template.m) in the freely-walking-optomotor repository. The template is based on protocol_27 and includes:

• Annotated sections for each part of the experiment (workspace setup, timing parameters, condition definitions, stimulus presentation, data saving)
• A comprehensive speed reference table mapping speed values to temporal frequencies for all common patterns
• Commented examples for different stimulus routing options (standard gratings, curtains, fixation bars, mixed routing)
• Automatic condition numbering (the 7th column of all_conditions is generated from the row index)

To create a new protocol:

1. Copy protocol_template.m and rename it (e.g. protocol_XX.m)
2. Edit the header comments to describe the scientific question and stimuli
3. Define your all_conditions matrix with the desired patterns, speeds, and durations
4. Choose the appropriate presentation function(s) in the stimulus routing section
5. Test with a short acclimation time (t_acclim_start = 30) before running the full experiment

Patterns for the G3 arena can be generated using the G4_pattern_generator_gui, but for this screen all patterns and position functions were made from scratch using custom scripts:

• Pattern scripts: script_to_make_patterns/
• Protocol scripts: protocols/ (includes a subfolder with helper functions)
• See the Protocols and Patterns index pages for documentation on each stimulus

---

How to analyse the data

The analysis pipeline is described in detail on the Analysis page. In brief, data processing proceeds in three levels:

1. Level 1 — per-cohort processing via process_freely_walking_data(), which generates overview figures and results files for each individual vial of flies.
2. Level 2 — cross-cohort analysis via process_screen_data(), which combines data across all strains and cohorts and creates comparison plots against the empty-split control flies.
3. Level 3 — statistical testing via make_summary_heat_maps_p27(), which generates p-value heatmaps comparing each strain to the empty-split control.

If you are analysing data from a different protocol, see Analysing a new protocol.

For interactive data exploration, see the Dashboard page — it provides a browser-based interface for comparing strains and conditions without writing code.

---

NoteTraining guide

A comprehensive training guide is available as a PDF at docs/training_guide/training_guide.pdf in the freely-walking-optomotor repository. The training guide covers the full data pipeline in detail — from running experiments through to the DATA struct — and includes diagrams, code walkthroughs, and a glossary of key terms. It is a useful companion to this documentation site, especially for understanding the processing functions and data structures in depth.