A set of MATLAB scripts to analyse basic parameters of (larval) locomotion, based on files generated by Multi-Worm Tracker. As used in the publication, Ataxia-linked SLC1A3 mutations alter EAAT1 chloride channel activity and glial regulation of CNS function.
There are two main functions for these scripts.
First, they call the java module, Choreography, which is packaged with Multi-Worm Tracker. Choreography recomputes the frame-by-frame speed, area and x,y coordinates of tracked objects. From this, we then calculate the path and distance travelled by each object.
Second, they generate plots to summarise these locomotor features.
With my best intentions I've tried to keep this code OS-agnostic (it should, in theory, run on Windows, Mac and other Unix-based systems), but if you run into any issues please feel free to reach out to me for help.
The parameters used to run Choreography are specified in the configuration files in the config directory. Please refer to Ohyama 2013 for an explanation of these parameters. In the case of this publication, these parameters are:
p: 0.0528 # mm per pixel
M: 0.18
t: 5
s: 0.1NOTE: If you intend to use these scripts for your own analyses, it will be important to modify these parameters for your specific recording/rig setup.
Choreography is invoked by these MATLAB scripts, which call the following commands.
# To compute object x position
java -jar ./packages/choreography/Chore.jar -t 5 -s 0.1 -p 0.0528 -M 0.18 -q --quiet –S -–nanless -o Dtx1234 -O x -N all --target <path/to/output/directory> <path/to/input/directory># To compute object y position
java -jar ./packages/choreography/Chore.jar -t 5 -s 0.1 -p 0.0528 -M 0.18 -q --quiet –S -–nanless -o Dty1234 -O y -N all --target <path/to/output/directory> <path/to/input/directory># To compute object speed
java -jar ./packages/choreography/Chore.jar -t 5 -s 0.1 -p 0.0528 -M 0.18 -q --quiet –S -–nanless -o Dts1234 -O speed -N all --target <path/to/output/directory> <path/to/input/directory># To compute object area
java -jar ./packages/choreography/Chore.jar -t 5 -s 0.1 -p 0.0528 -M 0.18 -q --quiet –S -–nanless -o Dte1234 -O area -N all --target <path/to/output/directory> <path/to/input/directory>Additionally, Choreography can be used to visualise the course of the experiment. This is not implemented in this MATLAB package, but can be run as long as you have the Chore.jar file downloaded. The command to generate this visualisation is:
# To visualise visualise the experiment
java -jar </path/to/Chore.jar> -t 5 -s 0.1 -M 0.18 -p 0.0528 --plugin Reoutline::exp --plugin Respine::0.23::tapered=0.28,1,2 --plugin SpinesForward::rebias --minimum-biased 3mm -S --plugin LarvaCast::angle --map -o srkN <path/to/input/directory>You must install:
Included:
- Colormaps
- append_pdfs
- yamlmatlab
You may also need to install ghostscript (required to generate vector graphics, like pdfs), for plots to be properly generated.
Download or clone this repository to the folder on your computer where you want to run your pipeline. Open MATLAB and navigate to the newly downloaded folder, MATLAB-Choreography.
IMPORTANT: Your working directory must be set to this folder in order for the package to run properly!
Set up the data and figure directories by running the function:
initialise_directories()Duplicate the default_config.yaml file in the config folder and modify the choreography parameters to suit your rig set up. Edit the configfile variable in main_choreography.m and main_plots.m to match the desired config file name.
Copy output data from Multi-Worm Tracker (MWT) into ./data/mwt_data. Anything data in this folder will be processed.
Run the command:
main_choreographyRun the command:
main_plotsCheck your working directory:
In order for the main_choreography and main_plot function to work, you must make sure to be running them from the correct directory. This will be the top-level folder of this repo, MATLAB-Choreography (unless you renamed it).
Check you toolboxes:
We ran into an issue where another installed MATLAB toolbox had a like-named function to that in the required Statistics & Machine Learning Toolbox. This caused the scripts to throw an error, as it tried to invoke the wrong function in the wrong toolbox. In this instance, we had to uninstall the conflicting toolbox, but there may be a workaround to specifically invoke the statistical toolbox's function.
Check your config file:
If you intend to use this package for your own analyses, please remember to change the parameter values in the config file to suit your particular setup. Failure to do this will give you some really weird data. Definitions for these parameters can be found in Ohyama 2013.
Check your config file paths:
On Windows, the filepath separator is the forward slash, /. On MacOS and other Unix-based systems, it is the backslash, \. Make sure the filepaths in your config folder are appropriate for your operating system!
# On Windows
C:\path\to\file
# On MacOS & Unix
~/path/to/file- Bug fix: Add
./codeand its subdirectories to the path ininitialise_directories.m - Add cbrewer package to the repo, as it's no longer available on the MATLAB File Exchange
- Updated README.md
- Added adjustable options to main_plots.m
- Added pause analyses
- prints pause events to csv
- generates pause ethogram
- generates pause timeseries, with s.d.
- Ridgelines now plot the full duration that objects are tracked for, rather than the first 30 seconds (time over which average metrics are calculated)
- Added 'curve' to the list of Choreography features output (config file)
- Added 'curve_smooth' parameter (moving mean, window = 21 frames)
- Added 'average curve' boxplot
- Changed the 'path' figures to be print all paths across a multi-page pdf, each page displaying 20 objects.
- Add 'additional_plots.m' - work in progress plots
- Curve violins
- Curve ridgeline - red highlights > 10 deg
- Curve traces - grey lines: all animals, red line: mean trace, red shaded area: standard deviation
- Area plots - fluctuation in average object area against time tracked.