This tutorial demonstrates how to use the Zanscript language to add visualised tracking traces (e.g., plots) to both the live view and recorded videos of your experiment. Tracking traces can show the movements of an animal over the length of a trial or can be written to trace movement over smaller stages of the experiment.
Commands to draw track traces
There are 2 DEFINE directives which need to be included in your script in order for the track traces to work. These are developmental settings and they should be placed at the top of your script prior to the ACTION MAIN.
DEFINE X_DRAWTRACKS 30011 DEFINE X_TRACKTIME 30016
DEFINE X_DRAWTRACKS 30011: setting to allow for the track drawing
DEFINE X_TRACKTIME 30016: setting to allow the length of track time to be changed in seconds. The default length of time the traces are visible before fading is 10 seconds.
SET(X_DRAWTRACKS,1) SET(X_DRAWTRACKS,0)
SET(X_DRAWTRACKS,1): begins to draw the traces onto the live video view. This command needs to be written into the script just prior to where you want the tracks to begin.
SET(X_DRAWTRACKS,0): turns off the track traces drawing.
SET(X_TRACKTIME,#)
SET(X_TRACKTIME,#): draws trace plots for the amount of time (in seconds) indicated with the number following the comma.
NOTE: There is a maximum limit of 180 seconds / 3 minutes (this is at 30 frames per second and adjusts for other frame rates).
Example script
DEFINE TIME_BIN 5
DEFINE NUM_SAMPLES 3
SET(TARGET_SIZE,2)
SET(DETECTOR_THRESHOLD,6)
SET(AUTOREF_MODE,MOVEMENT)
SET(AUTOREF_TIMEOUT,10)
DEFINE X_DRAWTRACKS 30011
DEFINE X_TRACKTIME 30016
ACTION MAIN
LOAD(ARENAS,"a6.bmp")
LOGCREATE("TEXT:TIME|TEXT:TEMP|TEXT:CONDITION")
LOGAPPEND("TEXT:A1|TEXT:A2")
LOGAPPEND("TEXT:B1|TEXT:B2")
LOGAPPEND("TEXT:C1|TEXT:C2")
LOGRUN()
AUTOREFERENCE()
SET(X_DRAWTRACKS,1)
SET(X_TRACKTIME,15)
INVOKE(SAMPLE,NUM_SAMPLES)
PICTURE("photo_arena")
COMPLETE
ACTION SAMPLE
LOGDATA(DATA_SNAPSHOT,"begin")
WAIT(TIME_BIN)
LOGDATA(DATA_SNAPSHOT,"end")
LOGDATA(DATA_SELECT,"begin")
LOGDATA(DATA_DELTA,"end")
LOGCREATE("RUNTIME|TEMPERATURE1|TEXT:SAMPLE")
LOGAPPEND("ARENA_DISTANCES:*")
LOGRUN()
COMPLETE
Script explanation
DEFINE TIME_BIN 5 DEFINE NUM_SAMPLES 3
The DEFINE command DEFINE TIME_BIN 5 details the time in seconds for the term TIME_BIN and DEFINE NUM_SAMPLES details the number of times the ACTION SAMPLE is executed later in the script.
SET(TARGET_SIZE,2) SET(DETECTOR_THRESHOLD,6)
These SET commands define the animal model tracking requirements which are dependent on animal size.
SET(AUTOREF_MODE,MOVEMENT) SET(AUTOREF_TIMEOUT,10)
These two DEFINE commands set the auto-reference tracking requirements.
AUTOREF_MODE,MOVEMENT uses a 'motion' method to track animals.
AUTOREF_TIMEOUT,10 indicates there is a 10 second period for capturing the animals in there arenas before tracking begins.
DEFINE X_DRAWTRACKS 30011 DEFINE X_TRACKTIME 30016
These are DEFINE statements for drawing tracking traces/plots. They are background directives, necessary at the beginning of a script, if you want to have traces.
DEFINE X_DRAWTRACKS 30011 is the background command to enable the system to draw the traces.
DEFINE X_DRAWTRACKS 30016 is the background command to enable the length of track time to be changed in seconds. The default length of time the traces are visible before fading is 10 seconds.
LOAD(ARENAS,"a6.bmp")
LOAD(ARENAS,"a6.bmp") loads the bitmap file for a 6-well plate which needs to be in the 'Asset Directory'. The bitmap outlines the size, shape and position of each of the arenas to be used in the experiment.
LOGCREATE("TEXT:TIME|TEXT:TEMP|TEXT:CONDITION")
LOGAPPEND("TEXT:A1|TEXT:A2")
LOGAPPEND("TEXT:B1|TEXT:B2")
LOGAPPEND("TEXT:C1|TEXT:C2")
LOGRUN()
The LOGCREATE, LOGAPPEND and LOGRUN commands can be used to write the headings which will be on the exported processed data file.
LOGCREATE specifies writing (or logging) of data. There is a character limit in Zanscript of 170 (previous software versions may have up to a 78 character limit). To continue writing a single line of data, LOGAPPEND can be used. In the example above, a heading label has been written for each of the arenas as they would be read on a 6-well plate.
LOGRUN tells the unit to now output the above data into the .csv file.
AUTOREFERENCE()
SET(X_DRAWTRACKS,1)
SET(X_TRACKTIME,15)
INVOKE(SAMPLE,NUM_SAMPLES)
PICTURE("photo_arena")
COMPLETE
AUTOREFERENCE() creates a reference image of the well plate prior to invoking the trials. It is needed for tracking.
SET(X_DRAWTRACKS,1) begins to draw the traces onto the live video view. This command needs to be written into the script just prior to where you want the tracks to begin.
SET(X_TRACKTIME,15) sets the traces to be plotted for the previous 15 seconds of movement before slowly fading from view.
INVOKE(SAMPLE,NUM_SAMPLES) tells the system to start the action called SAMPLE, which is detailed later in the script and repeats this action a number of times as defined at the top of the script by NUM_SAMPLES.
PICTURE("photo_arena") captures an image at this moment in the experiment and saves it to the Media directory under the name "photo_arena"
- In this example script, the tracks are started for the ACTION SAMPLE and an image is captured of the cumulative traces at the end of the NUM_SAMPLES repetitions.
Script download
To download the track_traces_demo script as a .zs file (file type Zantiks software reads), choose the Save File As option in the right-click dialogue box. Clicking on the script name hyperlink will open a read-only version of the script.
Script download: track_traces_demo.zs
