Locomotor data demo


This script demonstrates how to use the zanscript language to write a model organism behavioural assay that measures locomotion.

Top

Script explanation

The example shows how the LOGCREATE, LOGDATA and LOGRUN commands can be used in a script to enable you to download summarised results from your unit after the behavioural experiment finishes.

The first part:

INCLUDE zsys
SET(AUTOREF_MODE,0)            
SET(AUTOREF_TIMEOUT,30)
SET(DETECTOR_THRESHOLD,10) 
SET(SEARCH_DISTANCE,50)
SET(SEARCH_STEP,7)
SET(FILTER_RADIUS,15)
DEFINE UNIT_TIME 5
DEFINE TRIALS 3

The first part of the script:

  • Starts with INCLUDE zsys, you need this command to build any script in the unit.
  • Has six SET commands that give the unit the parameters / size of the model organism that you want to track (these values are for fake fish).
  • Specifies two DEFINE commands to detail values used later in the script.

Action Main:

ACTION MAIN
    LIGHTS(ALL,OFF)
    AUTOREFERENCE(0)
    SET(COUNTER1,COUNTER_ZERO)
    LOGCREATE("TEXT:|TEXT:|TEXT:|TEXT:|TEXT:TRIAL|TEXT:TRIAL_PERIOD"
    LOGAPPEND("TEXT:DISTANCE_TRAVELLED")
    LOGRUN()
    WAIT(UNIT_TIME)
    INVOKE(SIMPLE_LOCO,TRIALS)
    LOGCREATE("TEXT:|TEXT:|TEXT:|TEXT:TOTAL_TRIALS|COUNTER1")
    LOGRUN()      
COMPLETE

Action Main outlines the experiment:

  • All lights are turned off.
  • An autoreference image is made of the arena to enable tracking of one model organism - hence (0) is used.
  • COUNTER1 is SET to start counting from zero.
  • The LOGCREATE line of code (including the subsequent LOGAPPEND line) specifies a line of data which comprises 4 empty cells (TEXT:|), followed by three text cells (cell 5 contains the text "TRIAL", cell 6 contains the text "TRIAL_PERIOD" and cell 7 contains the text "DISTANCE_TRAVELLED")
  • LOGRUN tells the unit to output the data in the .csv data file as specified in the previous LOGCREATE line of code.
  • The unit waits for the previously defined amount of time in seconds (UNIT_TIME).
  • The Action SIMPLE_LOCO is invoked (starts). This Action, detailed below, repeats the number of times as defined earlier as TRIALS.
  • After the SIMPLE_LOCO trials are finished the LOGCREATE line specifies a line of data, the 4th cell contains the text "TOTAL_TRIALS", and the 5th cell contains the value that COUNTER1 has reached (in this instance the final trial number).
  • LOGRUN() outputs the data specified in the previous LOGCREATE command.

Action Simple_Loco

This Action, as invoked in Action Main, details the commands for this section of the experiment:

ACTION SIMPLE_LOCO
    SET(COUNTER1,COUNTER_INC)
    LOGDATA(DATA_SNAPSHOT,"begin")
    WAIT(UNIT_TIME)
    LOGDATA(DATA_SNAPSHOT,"after_unit_time")
    LOGDATA(DATA_SELECT,"begin")
    LOGDATA(DATA_DELTA,"after_unit_time")
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|COUNTER1|TEXT:UNIT_TIME")
    LOGAPPEND("ARENA_DISTANCES")
    LOGRUN()
COMPLETE

This Action details:

  • COUNTER1 is set to count the trials - i.e. count incrementally each time the Action occurs.
  • The unit logs the tracking data of the model organism, and calls this data "begin" - LOGDATA(DATA_SNAPSHOT,"begin")
  • The unit waits the UNIT_TIME as defined in seconds above.
  • The unit then makes another log of the tracking data of the model organism after the UNIT_TIME and calls this data "after_unit_time" - LOGDATA(DATA_SNAPSHOT,"after_unit_time")
  • The following two LOGDATA lines of code, LOGDATA(DATA_SELECT,"begin") and LOGDATA(DATA_DELTA,"after_unit_time"), instruct the unit to calculate the difference in data between the two snapshots taken, "begin" and "after_unit_time".
  • The LOGCREATE (and subsequent LOGAPPEND) lines then specifies content for a line of data, which includes the runtime this command was made, 3 empty cells, followed by the value for COUNTER1 (i.e. the trial number), the text (i.e. UNIT_TIME) in the 5th cell and in the 6th cell, the distance travelled in this period (ARENA_DISTANCES).
  • LOGRUN() command tells the unit to output the data into the .csv file as specified in the previous LOGDATA commands.
Top

Script download

Here you can download the locomotor data demo script as a .zs file. Right click on the download link below and download / save the file as a zanscript file, i.e. in the same format: locomotor_data_demo.zs .

Script download: locomotor_data_demo.zs

Top

Results output

The image below illustrates how the results data file details the distance travelled during each trial.  

You may download the full results data file, from a demo run of the service using fake fish, as a .csv file by clicking on the link here.

Screen Shot 2018 05 14 At 16 57 24
Results captured using fake fish during a service using the locomotor_data_demo script.