Overview

This section documents all experiment protocols used for freely-walking optomotor experiments on the G3 LED arena.

What is a Protocol?

A protocol is a MATLAB script that defines a complete experimental session, including:

Timing parameters: Acclimation periods, trial durations, inter-stimulus intervals
Stimulus conditions: Which patterns to show, at what speeds, in what order
Data logging: Video recording, temperature monitoring, metadata collection

Protocol Overview

Protocol	Description	Patterns	Conditions
Protocol_v1	Circadian optomotor experiments	2	0
Protocol_v10_all_tests	Testing spatial frequencies, speed, and trial lengths	4	8
protocol_10	Testing spatial frequencies, speed, and trial lengths	0	0
protocol_11	Protocol_v11	2	0
protocol_12	Short, all high contrast, replacing flicker with all ON	2	0
protocol_13	Very long num_trials_per_block (20, 40, 60)	2	0
protocol_14	Different interval stimuli - flicker, static gratings, ON/OFF	2	0
protocol_15	Testing skinny bars (4ON 12OFF) (12ON 4OFF)	3	3
protocol_16	Testing skinny bars (2ON 6OFF)	3	3
protocol_17	2ON 14OFF grating stimulus, flicker x4	2	0
protocol_18	Based on protocol 10 with curtain ON/OFF stimuli	3	6
protocol_19	Curtain ON/OFF and 2ON 14OFF stimuli	6	12
protocol_20	Shifted centre with 60deg patterns	3	6
protocol_21	Follow-up protocol 1 after protocol 19 screen	5	10
protocol_22	Follow-up protocol 2 - bar fixation, reverse phi	8	8
protocol_23	Test different contrast values for ON/OFF bars	2	2
protocol_24	Screen Protocol 1 - multi-stimulus	10	10
protocol_25	Short protocol for testing individual flies	4	4
protocol_26	Test different curtain stimuli (32 pixels)	6	4
protocol_27	Screen Protocol 2 - comprehensive stimulus set	12	12
protocol_28	Test reverse phi modifications	2	0
protocol_29	Screen Protocol 3 - with CW/CCW intervals	12	12
protocol_30	Different contrasts test	3	7
protocol_31	60deg and 15deg gratings - 4 speeds	8	10
protocol_32	60deg and 15deg gratings - long trials	7	5
protocol_33	Low luminance 60deg grating and flicker	4	2
protocol_r4	Reverse v4 - different switch intervals	2	0
protocol_v2	All high contrast optomotor patterns	2	0
protocol_v3	Optomotor stimulus one direction only	2	0
protocol_v4	Different switch intervals - short to long	2	0
protocol_v5	Short, all high contrast, for individual fly	2	0
protocol_v6	Optomotor with shifted centre of rotation	1	0
protocol_v7	Different speeds	2	0
protocol_v8	Optomotor freely walking with 4 pixel stripes	2	0
protocol_v9	Different spatial frequencies	6	0

Protocol Structure Reference

Timing Parameters

Parameter	Description	Typical Value
`t_acclim_start`	Dark acclimation before stimuli	300s (5 min)
`t_acclim_end`	Dark acclimation after stimuli	30s
`t_interval`	Inter-stimulus interval	15-30s
`t_flash`	Calibration flash duration	5s
`t_pause`	Command pause (hardware timing)	0.01s

Condition Array Format

The all_conditions matrix has 7 columns:

Column	Field	Description
1	pattern_id	Pattern number to display
2	interval_id	Pattern for inter-stimulus interval
3	speed_patt	Speed for main pattern (fps)
4	speed_int	Speed for interval pattern (fps)
5	trial_dur	Trial duration (seconds)
6	int_dur	Interval duration (seconds)
7	condition_n	Condition number

Speed Values

The speed_patt value = frames per second (fps). The actual temporal frequency depends on the pattern’s spatial period and step size:

TF (Hz) = fps × step_size / spatial_period_px

Velocity (deg/s) = TF × spatial_period_deg

Arena geometry: 192 columns = 360° → 1 pixel = 1.875°

Pattern	Type	Period	Step	spd 8	spd 16	spd 32	spd 64	spd 127
4	15° grating	8 px	1 px/f	1 Hz	2 Hz	4 Hz	8 Hz	~16 Hz
6	30° grating	16 px	1 px/f	0.5 Hz	1 Hz	2 Hz	4 Hz	~8 Hz
9	60° grating	32 px	1 px/f	0.25 Hz	0.5 Hz	1 Hz	2 Hz	~4 Hz
27	60° grating (2px step)	32 px	2 px/f	0.5 Hz	1 Hz	2 Hz	4 Hz	~8 Hz
63	15° grating (2px step)	8 px	2 px/f	2 Hz	4 Hz	8 Hz	16 Hz	~32 Hz

For non-grating patterns (flicker, curtains, fixation), the speed value simply controls the frame presentation rate.

Data Output

Each protocol run generates:

Video: UFMF format via SimpleBiasCameraInterface
LOG.mat: Trial timing, conditions, temperature, metadata
Google Sheets: Optional export for experiment tracking

Output folder structure (on the acquisition rig, under cfg.rig_data_folder — see Configuration & Paths):

rig_data_folder/
  YYYY_MM_DD/
    protocol_name/
      strain/
        sex/
          HH_MM_SS/
            LOG_YYYYMMDD_HHMMSS.mat
            REC_.ufmf

Protocol Categories

Screen Protocols (Comprehensive)

These protocols include a wide variety of stimuli for characterizing visual responses:

protocol_24: Screen Protocol 1 - Original comprehensive protocol
protocol_27: Screen Protocol 2 - Updated March 2025, includes reverse phi
protocol_29: Screen Protocol 3 - With intervals between CW/CCW

Versioned Protocols (Development Series)

Early development protocols used for establishing experimental parameters:

Protocol_v1 - v10: Progressive refinement of experimental design
Focus on different spatial frequencies, speeds, and trial structures

Numbered Protocols (Specific Experiments)

Purpose-specific protocols for particular experiments:

protocol_10-13: T4T5 experiments with varying parameters
protocol_15-16: Skinny bar gap testing
protocol_18-19: Curtain stimuli
protocol_30-33: Contrast and luminance variations

Protocol Lineage

v1 ─> v2 ─> v3, v4/r4, v5, v6, v7, v8, v9
                                              ╲
                                v10 ─> 10 ─> 18 ─> 19 ─> 24 (Screen 1) ─> 25
                                                     │                  ╲
                                                     ├─> 20              27 (Screen 2) ─> 29 (Screen 3)
                                                     ├─> 21                             ╲
                                                     ├─> 22                              ├─> 30
                                                     └─> 23                              ├─> 31 ─> 32
                                                                                         └─> 35 ─> 36
Standalone: 15/16, 17, 26, 28, 33/34, 37

Adding a New Protocol to the Documentation

When you create a new experiment protocol, follow these steps to add it to this documentation:

Step 1: Create the Protocol File

Start from the protocol template at src/protocols/protocol_template.m. This template includes:

A documentation header with fields for rationale, stimulus summary, and timing
Comprehensive speed reference tables with computed Hz values for all common patterns
Column-by-column documentation of the all_conditions matrix
Annotated routing examples for all 8 stimulus presentation functions
Standard initialization, logging, and cleanup code

Copy the template and rename it:

% In src/protocols/:
% 1. Copy protocol_template.m to protocol_XX.m
% 2. Fill in the docstring header
% 3. Edit the all_conditions matrix
% 4. Choose the appropriate routing in Section 5

See also src/protocols/PROTOCOL_REFERENCE.md for a quick-reference table of all existing protocols, pattern properties, and lineage.

Step 2: Generate Documentation

From the freely-walking-optomotor directory, run:

cd /path/to/freely-walking-optomotor
pixi run -e default --manifest-path python/freely-walking-python/pixi.toml \
    python docs_generator/generate_protocol_docs.py \
    protocols/protocol_XX.m

This will:

Parse the protocol file and extract metadata
Create a .qmd documentation page in reiser-documentation/Freely-walking/

Step 3: Preview and Deploy

cd /path/to/reiser-documentation
quarto preview

Once satisfied, commit and push to deploy.

Regenerating All Protocol Documentation

To regenerate documentation for all protocols:

cd /path/to/freely-walking-optomotor
pixi run -e default --manifest-path python/freely-walking-python/pixi.toml \
    python docs_generator/generate_protocol_docs.py