Troubleshooting

This page covers common problems and their solutions, organised by the stage at which they occur. Click any issue to expand the details.

Setup & configuration

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

Solution: Ensure the nested_RF_stimulus/src directory and all subdirectories are on the MATLAB path:

addpath(genpath('C:\matlabroot\G4_Protocols\nested_RF_stimulus\src'));

Also verify that G4_Display_Tools is on the path: which PanelsController should return a valid path.

Symptom: Undefined function 'circ_vmpar' during analysis.

Solution: Install the Circular Statistics Toolbox from the MATLAB Add-On Explorer. See Installation & Setup.

Symptom: File not found errors referencing C:\matlabroot\... or /Users/burnettl/....

Solution: Several files contain hardcoded paths specific to the original rig. Update them for your system — see the hardcoded paths table in Installation & Setup.

Protocol 1 issues

Symptom: Protocol starts but no stimuli appear on the arena.

Possible causes:

  • Arena is not powered on
  • PanelsController cannot connect — try running PanelsController standalone to test the connection
  • The .g4p file path is incorrect in the experiment conductor

Symptom: The Log Files/ folder is empty after running Protocol 1.

Possible causes:

  • The experiment was aborted (check Aborted_Experiments/ folder)
  • The processing_settings.mat is missing or misconfigured
  • The acquisition channels were not set to the correct sampling rate (should be 10,000 Hz)

Symptom: Protocol 1 completes but no grid plots appear.

Solution: Check the processing_settings.mat file:

  • settings.is_ephys_grid must be 1
  • settings.neutral_frame must be 1
  • settings.grid_columns and settings.grid_rows must match the flash sizes used
  • settings.path_to_protocol must point to the correct .g4p file

Between Protocol 1 and Protocol 2

Symptom: A warning dialog appears when running generate_protocol2() saying the stimulus area extends beyond the arena boundary.

Explanation: The code in generate_protocol2.m (lines 78-89) checks whether the 30 x 30 pixel Protocol 2 area, centred on the peak_frame location, would extend off-screen. If the peak_frame is within ~15 pixels of any arena edge, the stimuli will be partially clipped.

Options:

  • Proceed anyway — the protocol will still run, but stimuli near the edges of the area will be cut off
  • Decide not to run Protocol 2 for this cell if the clipping would be too severe
  • If the RF is consistently near the edge, consider creating a new Protocol 1 version that covers a different region of the arena

Symptom: The cell responds similarly to both bright and dark flashes in Protocol 1.

Solution: Choose the contrast with the slightly larger response. You can always run Protocol 2 twice — once for each contrast — since the script returns the inverse contrast peak_frame at the end.

Symptom: Voltage deflections in the grid plots are small or inconsistent.

Possible causes:

  • The recording quality has degraded — check the seal resistance
  • The cell type may have a small receptive field that falls between flash positions
  • The cell may not respond strongly to static flashes

Decision: If responses are very weak or noisy, Protocol 2 (20-25 minutes) may not yield useful data. Consider re-patching or moving to a different cell.

Protocol 2 issues

Symptom: generate_protocol2() fails when trying to connect to the arena.

Solution:

  • Check that the arena is powered on
  • Try running PanelsController manually to test the connection
  • Close any other MATLAB instances that might have an open connection to the controller
  • Restart the arena controller if necessary

Symptom: Error during G4_TDMS_folder2struct() at the end of Protocol 2.

Possible causes:

  • The TDMS files are still being written (wait a moment and try again)
  • The TDMS files are corrupted (check file sizes — they should be >0 bytes)
  • The G4_Display_Tools TDMS conversion function has a bug or version mismatch

Workaround: You can manually convert the TDMS files after the experiment:

log_folder = 'C:\matlabroot\G4_Protocols\nested_RF_protocol2\data\YYYY_MM_DD_HH_MM\Log Files\MM-DD-YYYY_HH-MM-SS-ms';
G4_TDMS_folder2struct(log_folder);

Symptom: Protocol 2 takes significantly more or less than 20-25 minutes.

Possible causes:

  • Stimulus parameters were modified (different speeds, more/fewer stimuli)
  • The number of repetitions was changed
  • Communication delays with the arena controller

The estimated duration is printed to the MATLAB console at the start of run_protocol2().

Analysis

Symptom: load_protocol2_data() cannot find the converted log file.

Solution: Check the Log Files/ folder. If only raw .tdms files are present, the TDMS conversion may have failed. Run it manually:

cd('YYYY_MM_DD_HH_MM');
log_folder = dir('Log Files/**/');
G4_TDMS_folder2struct(fullfile('Log Files', log_folder(end).name));

Symptom: Analysis runs but figures and results are not saved, or a “folder not found” error appears.

Solution: The PROJECT_ROOT variable in process_protocol2.m (line 45) is set to a path specific to the developer’s computer. Update it to a valid path on your system where you want results saved.

Possible causes:

  • The recording was interrupted mid-experiment (incomplete data)
  • Stimulus timing is unusual due to communication delays
  • A different protocol version was used that has different timing

Debugging approach:

  1. Load the data manually: load('Log Files/G4_TDMS_Logs_*.mat')
  2. Plot the frame position data: plot(Log.ADC.Volts(1,:))
  3. Verify the expected stimulus structure is present (flashes followed by bar sweeps)
  4. If timing is off, the parsing functions may need their threshold values adjusted

Data recovery

If Protocol 2 is interrupted mid-experiment:

  • The TDMS files recorded up to the point of interruption should still be in the Log Files/ folder
  • You can attempt to convert them with G4_TDMS_folder2struct()
  • The analysis may partially work, but will likely fail on the missing repetitions
  • The patterns, functions, and parameters are already saved in the experiment folder, so you could re-run the experiment without re-generating (though in practice, running generate_protocol2() again is simpler)

Quality control reference

The codebase includes several quality check plotting functions in src/analysis/plotting/ that can help diagnose data issues:

Function Purpose
plot_quality_check_data_full_rec Plots the full voltage recording to check for drift, noise, or artifacts
plot_quality_check_flash_timing Verifies that flash stimulus timing matches expectations
plot_quality_check_var_reps_prctile Checks variance across repetitions to identify unreliable responses
plot_quality_check_data_bounds Verifies that voltage data is within expected ranges

These can be called after loading the data to verify recording quality before running the full analysis pipeline.