Guidelines for New Analysis Scripts

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. combineflag is a 1/0 indicator of whether multiple days should be selected. It is optional, but the gui supports it.
• 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.

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. It's also recommended that these arguments are explained 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 what's available within the block:

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

dirlist :: list of directories to be plotted (conversion into jstructs/stats can be handled by calling load_jstructs or load_stats).

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). Be careful about attempting to 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));