Guidelines for New Analysis Scripts - GoldbergLab/RodentJoystick GitHub Wiki

Tips for writing new analysis scripts (for the GUI and to interact with other functions)

  • To work with the GUI, an analysis script must take the following arguments: dirlist and ax. dirlist is a struct representation of a list of directories. ax is a handle to an axes - the script can generate its own axes if ax is empty.
  • Limit the script to one axes unless multiple axes are unavoidable (like trajectory_analysis). If the script generates multiple plots, but ones that are not inherently linked (like activity_summary_heat_maps), break the function into modular pieces that can be called individually.
  • If the above requirement seems arbitrary, consider splitting up data generation/analysis and plotting. See the interactions for activity/velocity/acceleration heat maps to explain this better.
  • Supported arguments: The following arguments are not required, but they may be useful and are supported by pp_gui. combineflag - 0/1/2, see load_stats for full documentation (combining multiple directories in dirlist), smoothparam - smooth parameter for moving average box filter, normalize - 0/1 flag indicating whether to normalize a histogram to a probability distribution, laser_comparison - 1/2/3, see plot_all_days for use, but can be used to select no comparison, or compare laser v all catch or laser v resampled trajectories.

##How to add an analysis function to pp_gui. The following three functions must be changed in order for pp_gui to support the new script:

plot_all_days, load_arguments, populate_function_list

However, each of these only requires a few lines. populate_function_list simply generates the list of functions/options to select from the drop down menus. load_arguments prepares the appropriate argument slots in the window. plot_all_days does the actual plotting.

  • populate_function_list: add a string title for the plot to the cell array function_list EX:
'Acceleration Heat';
'Acceleration Variation Heat';
'My New Function';
'Angle Distribution (Linear)';
  • load_arguments: add an elseif block for the response when the function is selected. It is important that the text in the elseif block exactly matches the entered string in populate_function_list. Update arg1, arg2, arg3, arg1label, arg2label, arg3label as needed, setting them to strings, not numbers. arg1, arg2, arg3 are the default arguments. If an argument is going to be used, it must be set. I.e. - it is not okay to plan to use the space assigned to arg2, but leave it empty - this can cause crashes later. It is not necessary to set unused arguments/labels. It should be noted that argument labels have a limit of just 8 characters before becoming truncated. Comment these arguments to avoid confusion later. EX:
elseif strcmp(plotname, 'Hold Time Distribution (Trajectories)')
    arg1 = '20'; 
    arg1label = 'Interv'; %Histogram interval (ms)
    arg2 = '2000'; 
    arg2label = 'End Time'; %what time range to plot
elseif strcmp(plotname, 'My New Function')
    arg1 = '5';
    arg1label = 'MyArg'; %my argument
elseif strcmp(plotname, 'Rewarded Hold Time Distribution')
    arg1 = '50'; 
    arg1label = 'Interv'; %Histogram interval (ms)
    arg2 = '1500';
    arg2label = 'End Time'; %what time range to plot
  • plot_all_days: This file is where the actual plotting happens. Here you parse the given arguments and plot the function onto ax: Here's the list of arguments available within the block for plotting: dirlist :: list of directories to be plotted (conversion into jstructs/stats can be handled by calling load_jstructs or load_stats).

combineflag :: 1/0 flag indicating whether the days should be combined.

normalize :: 1/0 flag indicating whether the probability distribution should be normalized

smoothparam :: (currently unsupported) value indicating size of frame for smoothing parameter.

arg1, arg2, arg3 :: arg1, arg2, arg3 are strings representing user input to the argument slots. The caller has to convert them to numbers if desired (using str2num). Do not convert argument slots that were not changed in load_arguments.

axes(axnum) :: this is the available axes for the function to plot on. While technically one can plot on multiple axes using this method, be careful since this can mess up orderings/plotting. Like before, it is important that the string to be matched to is the exact same as the ones entered in load_arguments and populate_function_list. EX:

elseif strcmp(plotname, 'Nosepoke Joystick Onset Distribution')
    arg1 = str2num(arg1);
    np_js_distribution(dirlist, arg1, combineflag, 1, axes(axnum));
elseif strcmp(plotname, 'My New Function')
    arg1 = str2num(arg1);
    my_new_function(dirlist, arg1, 1, combineflag, axes(axnum));
elseif strcmp(plotname, 'Nosepoke Post Onset Distribution')
    arg1 = str2num(arg1);
    np_post_distribution(dirlist, arg1, combineflag, 1, axes(axnum));