Customization

BehaviorDEPOT is written to be flexible to enable users to generate custom classifiers for unique behaviors or arena situations. If you’re curious about any of the code, want to tweak it, or create your own classifier, you can access the underlying scripts by simply right clicking on the app and navigating to where the app files are installed. To edit the GUI, you can open the BehaviorDEPOT.mlapp file in MATLAB’s ‘App Designer’.

How to Build a Classifier

Classifier File Structure

• BehaviorDEPOT classifiers consist of 2 MATLAB files:

  • classifier file
  • parameters file ('P' file)

• A classifier is essentially an analysis script that can be applied to tracking labels or metric calculations in order to label a behavior.

• For example, our freezing classifier uses a combination of a low linear velocity and low angular velocity to pick freezing frames.

• Each classifier is a MATLAB function contained within a script in the 'classifiers' folder that calls the same input parameters--Metrics, Tracking, and Params.

• The 'classifier' folder is accessible through the GUI or at the application's install location.

• Both of classifier and 'P' file must be in the application's 'classifier' folder in order to be detected.

P File Structure

• Each 'P' file contains the parameters used by a particular classifier.
• These files are MATLAB functions contained within a script.
• In order to be associated with the correct classifier, the file must follow the following naming convention: 'P_[classifier name].m'
• Each classifier file contains the instructions to transform tracking and/or metric data into behavior labels.

Classifier Convolution

• Each classifier uses its specific criteria to extract raw behavior labels.
• It is often advantageous to smooth the raw frames to mitigate tracking/metric calculation errors.
• BehaviorDEPOT includes a convolution function to apply to raw behavior labels.

Classifier Templates

• Templates with annotation useful for building a new classifier are included on the BehaviorDEPOT Github page.
• Read these templates for examples of how to build classifiers, including use of BehaviorDEPOT classifier-building functions.
• Templates can be used as starting point for new classifiers as well as examples of support function usage.

Classifier Support Functions

• BehaviorDEPOT comes packaged with built-in functions designed to support building of classifiers.
• See the classifier template for examples of built-in function usage.

Customizing Existing Classifiers

• Existing classifiers can be easily modified by opening the associated file in the 'classifiers' folder.
• Edit P files to adjust default parameter values for each classifier.
• Edit classifier files to customize how classifier analysis is done.

How to Add New Metrics Calculations

• Metrics are calculated in the script: calculateMetrics.m
• New metrics can be added to the script at any point beneath METRIC CALCULATIONS (line 70)
• calculateMetrics.m uses a MATLAB structure called 'tempTracking' when calculating metrics; this structure contains info in the same format as the Tracking.mat output from the main Analysis Module (see 'Outputs')
• When using tempTracking, access the data directly without using 'Raw' or 'Smooth' (e.g. tempTracking.Nose)
• Add your calculation and save it to the Metrics structure (e.g. Metrics.(new_metric) = new_metric;)

Adding Custom Classifiers

• New classifiers can easily to installed into BehaviorDEPOT.
• Simply add the classifier file and associated 'P' file to the 'classifiers' folder (accessible from the GUI or app files).
• Ensure 'P' is named 'P_[classifier name]' where [classifier name] is the full filename of the classifier file.

Editing the BehaviorDEPOT App

• We welcome customization, suggestions, and augmentations of officially-released code.
• Please reach out to authors if you need help implementing customization of BehaviorDEPOT code or would like to integrate your code into the main release.