Troubleshooting

This page collects common issues grouped by topic. Click any issue to expand the details.

Setup & configuration

Symptom: MATLAB reports that functions or directories cannot be found.

Solution: Run setup_path.m to add all src/ subdirectories to the MATLAB path, then check that get_config().project_root points to an existing directory:

cfg = get_config();
assert(isfolder(cfg.project_root), 'project_root does not exist: %s', cfg.project_root);

Symptom: Undefined function or variable 'process_freely_walking_data' or similar errors.

Solution: Ensure the freely-walking-optomotor repository is on the MATLAB path:

addpath(genpath('/path/to/freely-walking-optomotor'));

Verify by running which process_freely_walking_data — it should return a valid path.

Symptom: Errors referencing functions like ranksum, fittype, or circ_vtest.

Solution: The following MATLAB toolboxes are required:

Toolbox Required for
Statistics and Machine Learning Toolbox Statistical tests (ranksum, FDR correction)
Image Processing Toolbox Video processing
Circular Statistics Toolbox Phototaxis analysis (circ_vtest, Watson-Williams test)

Install missing toolboxes via MATLAB’s Add-On Explorer.

Symptom: Scripts fail with errors about NETWORK_* paths not existing.

Solution: The NETWORK_* paths require the network drive to be mounted. On Windows this is typically automatic via domain login. On Mac, connect via Finder: Go > Connect to Server > smb://prfs.hhmi.org/reiserlab/oaky-cokey.

Symptom: ModuleNotFoundError: No module named 'config' or similar import failures.

Solution: Make sure sys.path.insert reaches the repo root before importing from config.config. The depth depends on the script’s location in the directory tree. For example, scripts in python/automation/daily_processing/ need four levels:

sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))

Symptom: Scripts fail on a different machine than the one they were originally written on.

Solution: Several files contain paths specific to the original computers. If running on a different machine, update these:

Location What to change
generate_circ_stim_ufmf.m Path to JAABA repository (currently C:\Users\labadmin\Documents\GitHub\JAABA-master)
generate_circ_stim_ufmf.m Path to patterns folder (patterns/Patterns_optomotor/)
Processing functions Root data directory paths
make_summary_heat_maps_p27.m ROOT_DIR for results — specific per user

Hardware & acquisition

Symptom: MATLAB pop-up appears asking for the user to enter the port number for the camera.

Solution: The port on the acquisition computer is Port 4. Just type 4 into the pop-up and press Enter. This should allow the protocol to run and the camera to start acquiring.

Symptom: The protocol script runs but no stimuli appear on the arena.

Possible causes:

  • Arena is not powered on or the controller is disconnected
  • PControl cannot connect — try running PControl standalone to test the connection
  • The panel_com functions are not on the MATLAB path — verify G4_Display_Tools is installed

Symptom: MATLAB command window shows that the protocol is running, but the LED arena remains dark.

Solution: Stop the protocol in the MATLAB editor tab. Stop BIAS from acquiring frames. Delete the folder that has been created for the experiment. Turn the controller off and the switch on the side of the LED arena off. Wait for 10s, then switch the LED arena switch on. Wait for the test pattern to appear, wait for 5s, then switch on the controller again. Restart the protocol script in MATLAB. This should resolve the issue. If not, check the power supply and connections to the arena. Unfortunately, the problem occurs not too infrequently and we don’t have a good idea of why. Normally, some combination of turning things off and on again seems to fix it.

Symptom: The protocol runs but no .ufmf video file is created.

Possible causes:

  • BIAS was not started before the protocol script
  • The camera is not acquiring (check that IR illumination is on and the frame rate is 30 fps)
  • Disk space is full on the recording drive

Symptom: No LOG_*.mat file appears in the experiment directory after the protocol finishes.

Possible causes:

  • The protocol was interrupted before completion (check MATLAB command window for errors)
  • The output directory path in the protocol script is incorrect
  • MATLAB did not have write permissions to the directory

Symptom: The .ufmf video shows a dark image with no flies visible.

Possible causes:

  • IR illumination was not turned on
  • The camera exposure settings in BIAS are too low
  • The arena LEDs were overpowering the IR illumination (LEDs should be green, not visible to the IR camera)

Tracking

Symptom: Fewer flies tracked than were loaded into the arena. The n_fly_data array shows a large number in the third element (flies removed).

Explanation: The function check_tracking_FlyTrk removes any tracked object whose frame count does not match the mode frame count. This catches cases where:

  • A fly’s tracking was split across multiple identities
  • A non-fly object (debris, shadow) was briefly tracked
  • A fly stopped moving and was lost by the tracker

What to check:

  • Verify the arena was clean before loading flies
  • Check that lighting conditions were consistent throughout the experiment
  • Review the .ufmf video to see if flies were genuinely lost from tracking

Symptom: Unrealistic velocity spikes in the timeseries plots.

Explanation: Frames where the forward velocity exceeds 50 mm/s are treated as tracking errors and set to NaN. These are then filled using interpolation. If many consecutive frames exceed this threshold, the interpolation may produce unusual values.

What to check:

  • A few isolated spikes are normal and handled automatically
  • Persistent high-velocity regions suggest the tracker jumped between flies — re-run FlyTracker with adjusted settings or exclude the cohort

Processing

Symptom: The batch processing function fails on a specific experiment folder.

Common causes:

  • Missing files: Ensure the experiment folder contains a .ufmf video, LOG_*.mat file, and a subdirectory with trx.mat and *-feat.mat
  • Date format: The function expects the date folder to be named YYYY_MM_DD (underscores, not hyphens)
  • Empty LOG: If the protocol was aborted, the LOG file may be incomplete

Debugging approach:

  1. Navigate to the experiment folder manually
  2. Try running process_data_features directly on that folder
  3. Check that load('LOG_*.mat') works and the LOG structure contains the expected fields

Symptom: Data from the same strain appears under different names in the combined DATA structure.

Explanation: Strain names are extracted from the LOG metadata and can vary due to typos or inconsistent naming. The function check_strain_typos attempts to normalise common variations, but may not catch all cases.

Solution: Check the strain names in the LOG files for consistency. If needed, update the mapping in check_strain_typos.m.

Symptom: Error when trying to combine data across cohorts, often referencing missing fields or unexpected structure.

Common causes:

  • Missing condition numbers: Older protocols (before protocol 24) do not save condition numbers to the LOG file. The function requires this field. Use a version-specific parser (e.g. comb_data_across_cohorts_cond_v14.m) for older protocols.
  • Mismatched protocols: Experiments from different protocol versions may have different numbers of conditions or different timing structures
  • Incomplete experiments: If a protocol was interrupted, some conditions may be missing from the LOG

Symptom: Plots show flat lines or the DATA structure has empty fields.

What to check:

  • Verify the processed *_data.mat file exists and contains comb_data with the expected fields
  • Check n_fly_data — if all flies were removed during tracking QC, comb_data arrays will be empty
  • Confirm the LOG file has the correct condition definitions (pattern IDs, speed values)

Dashboard

Symptom: The dashboard starts but shows no data or reports missing files.

Solution: The dashboard reads from RESULTS_PATH / "protocol_27" by default. Ensure you have run process_freely_walking_data for the relevant dates, or point the dashboard to a different protocol directory.

Quality control reference

The processing pipeline generates several overview figures that can help diagnose data quality issues:

Figure What it shows What to look for
Locomotion histograms (make_overview) Distribution of velocity, angular velocity, and turning rate Bimodal distributions may indicate mixed fly health; very narrow distributions suggest most flies were stationary
Full-experiment timeseries (plot_all_features_filt) All flies’ metrics across the entire protocol with coloured condition markers Baseline drift, sudden changes in activity, or missing condition periods
Acclimation timeseries (plot_all_features_acclim) Metrics during the 5-minute dark acclimation Flies should settle to a stable baseline; consistently high activity may indicate stress or arena vibration
Per-condition plots (plot_allcond_onecohort_tuning) Mean + SEM for each condition Responses should be consistent across the two repetitions; large SEM suggests variable behaviour