Data demo


This demo script illustrates how you can write a script, for a model organism behavioral assay, which instructs the unit to collect and process data in real time.

Top

Script explanation

The script below is for a study using 2 arenas, for 2 single housed fish, who swim over two zones; each zone is marked with a different stimulus, in this case the colours blue and green are use.  

First part:

INCLUDE zsys
SET(AUTOREF_MODE,1)            
SET(AUTOREF_TIMEOUT,30)
SET(DETECTOR_THRESHOLD,10) 
SET(SEARCH_DISTANCE,50)
SET(SEARCH_STEP,7)
SET(FILTER_RADIUS,15)
DEFINE COLOUR WHITE               
DEFINE CIRCLE 1
DEFINE SQUARE 2                          
SETLIGHT(LIGHT1,SQUARE,300,500,1000)    
SETLIGHT(LIGHT2,SQUARE,1300,500,1000)
LOAD(DETECTORS,"test2_arenas2w")             
LOAD(ARENAS,"arenas2l")              
LOGDATA(LOGDATA_FORMAT,"A1,2 Z1,2") 
DEFINE UNIT_TIME 10                         
DEFINE PROBE_TIME 5

The first part of the script (seen above) details the following instructions for the unit which are applicable throughout the experiment: 

  • Include zsys - this must be included in all scripts. 
  • The next group of commands - SET - are the settings for the tracking of the particular model organism that you are studying.
  • The DEFINE and SETLIGHT commands define the shape, positions and sizes of the lights that will appear on the screen.
  • The LOAD commands load the detector zones as set out in the bitmap which must be saved in exactly the same style (upper and lower case) in the Assets directory: test_2arenas2w.bmp. The same applies for the arenas, which details the shape and orientation of the different arenas for the fish.
  • The DEFINE commands following detail the number of seconds to wait when instructed in the script below.

Action Main

ACTION MAIN                                    
    LIGHTS(ALL,OFF)                         
    AUTOREFERENCE(0)                            
    INVOKE(HABITUATION,1)                  
    INVOKE(BASELINE,1)                        
COMPLETE

This next set of commands (above) details the order of the whole experiment. In this case:

  • First the lights are all turned off.
  • Next an auto reference is taken of the tank. After this point the unit starts tracking the movement of the model organisms, monitoring changes in x and y coordinates and keeping a tally of distance travelled, time spent in different detector zones, time spent in arena, number of visits to detector zones. 
  • The first part of the experimented is invoked, HABITUATION, once. The details of the HABITUATION period will be detailed in its own ACTION section below.
  • The next part of the experiment is invoked, BASELINE, once. The details of this period will be detailed below similarly.

Complete indicates this is the end of the ACTION MAIN commands.

Action Habituation

ACTION HABITUATION                         
                                            
    LIGHTS(LIGHT1,BLUE)                     
    LIGHTS(LIGHT2,GREEN)                    
    WAIT(UNIT_TIME)                      
    LIGHTS(LIGHT1,GREEN)                     
    LIGHTS(LIGHT2,BLUE)                     
    WAIT(UNIT_TIME)
    LIGHTS(ALL,OFF)                         
    WAIT(PROBE_TIME)
    
COMPLETE

The ACTION HABITUATION section details the actions for this period:

  • LIGHT1 will come on as colour blue - the position of LIGHT1 was detailed in the first section of the zanscript.
  • LIGHT2 will come on as colour green at the same time - again its position has already been detailed.
  • The unit will then wait for the UNIT_TIME (as defined earlier) before LIGHT1 illuminates as green and LIGHT2 as blue. These light settings on the screen will wait for the unit time before turning off. The unit then waits for the PROBE_TIME, as set out above, before this action is complete.

Action Baseline

This is a fairly long section of code so I have broken the ACTION BASELINE into a couple of sections to explain it.

ACTION BASELINE                             
    VIDEO(60,"baseline")                  
    
    LIGHTS(LIGHT1,BLUE)
    LIGHTS(LIGHT2,GREEN)
    LOGDATA(DATA_SNAPSHOT,"begin")           
    WAIT(UNIT_TIME) 
    LOGDATA(DATA_SNAPSHOT,"after10sec")                                                 
    LOGDATA(DATA_SELECT,"begin")                                                    
    LOGDATA(DATA_DELTA,"after10sec")                                                 
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:BASELINE|TEXT:FIRST10SEC")
    LOGAPPEND("TEXT:VARIABLE|TEXT:ARENA1_ZONE1_BLUE|TEXT:ARENA1_ZONE2_GREEN")        
    LOGAPPEND("TEXT:ARENA2_ZONE1_BLUE|TEXT:ARENA2_ZONE2_GREEN")
    LOGRUN()
    INVOKE(WRITEDATA,1)

In the above section of code:

  • The first command tells the unit to record a video of the experiment for 60 seconds, which will be saved in the media directory as a video file called baseline.avi
  • The next commands are then very similar to subsequent parts of the ACTION BASELINE commands, instructing the unit to change the screen lights and record the organism's tracking data at 10-second intervals:
    • The two lights are set as blue and green and positioned on the screen
    • The unit takes a snapshot of the data at this moment 
    • After waiting (for 10 seconds, the defined WAIT_TIME) the unit takes another snapshot of the data. It then extracts the differences between the two snapshots, following the DATA_SELECT and DATA_DELTA commands.
    • The LOGCREATE, and subsequent LOGAPPEND, lines detail the labels for the cell data to be included in the results file. N.b. each line of code can be a maximum of 78 characters, if you have a longer line of code you need to use the LOGAPPEND command to run it over a new line. The LOGCREATE command for each cell is written sequentially and separated with a line | , these include:
      • RUNTIME  - which details the exact time this line of data was recorded.
      • TEXT: - the space after the colon indicates that this cell is left empty.
      • TEXT:BASELINE - any word written after the colon is written in the cell, in this instance 'BASELINE' is written in the cell.
    • LOGRUN instructs the unit to output all the previous LOGCREATE commands.
    • The INVOKE(WRITEDATA) command then tells the unit to carry out the ACTION WRITEDATA (which is detailed below).
  • The last set of commands in this ACTION tell the unit to record the tracking data for the whole 60 second period.
LIGHTS(LIGHT1,GREEN)                    
    LIGHTS(LIGHT2,BLUE)
    WAIT(UNIT_TIME)  
    LOGDATA(DATA_SNAPSHOT,"after20sec")                                             
    LOGDATA(DATA_SELECT,"after10sec")                                                        
    LOGDATA(DATA_DELTA,"after20sec") 
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:BASELINE|TEXT:SECOND10SEC")              
    LOGAPPEND("TEXT:VARIABLE|TEXT:ARENA1_ZONE1_GREEN|TEXT:ARENA1_ZONE2_BLUE")
    LOGAPPEND("TEXT:ARENA2_ZONE1_GREEN|TEXT:ARENA2_ZONE2_BLUE")
    LOGRUN()
    INVOKE(WRITEDATA,1)
    
    LIGHTS(LIGHT1,BLUE)                     
    LIGHTS(LIGHT2,GREEN)
    WAIT(UNIT_TIME)
    LOGDATA(DATA_SNAPSHOT,"after30sec")                                             
    LOGDATA(DATA_SELECT,"after20sec")                                                    
    LOGDATA(DATA_DELTA,"after30sec") 
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:BASELINE|TEXT:THIRD10SEC")               
    LOGAPPEND("TEXT:VARIABLE|TEXT:ARENA1_ZONE1_BLUE|TEXT:ARENA1_ZONE2_GREEN")
    LOGAPPEND("TEXT:ARENA2_ZONE1_BLUE|TEXT:ARENA2_ZONE2_GREEN")
    LOGRUN()
    INVOKE(WRITEDATA,1)
    
    LIGHTS(LIGHT1,GREEN)
    LIGHTS(LIGHT2,BLUE)
    WAIT(UNIT_TIME)
    LOGDATA(DATA_SNAPSHOT,"after40sec")                                             
    LOGDATA(DATA_SELECT,"after30sec")                                                    
    LOGDATA(DATA_DELTA,"after40sec") 
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:BASELINE|TEXT:FOURTH10SEC")
    LOGAPPEND("TEXT:VARIABLE|TEXT:ARENA1_ZONE1_GREEN|TEXT:ARENA1_ZONE2_BLUE")       
    LOGAPPEND("TEXT:ARENA2_ZONE1_GREEN|TEXT:ARENA2_ZONE2_BLUE")
    LOGRUN()
    INVOKE(WRITEDATA,1)
        
    LIGHTS(LIGHT1,BLUE)
    LIGHTS(LIGHT2,GREEN)
    WAIT(UNIT_TIME)
    LOGDATA(DATA_SNAPSHOT,"after50sec")                                             
    LOGDATA(DATA_SELECT,"after40sec")                                                   
    LOGDATA(DATA_DELTA,"after50sec") 
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:BASELINE|TEXT:FIFTH10SEC")               
    LOGAPPEND("TEXT:VARIABLE|TEXT:ARENA1_ZONE1_BLUE|TEXT:ARENA1_ZONE2_GREEN")
    LOGAPPEND("TEXT:ARENA2_ZONE1_BLUE|TEXT:ARENA2_ZONE2_GREEN")
    LOGRUN()
    INVOKE(WRITEDATA,1)
        
    LIGHTS(LIGHT1,GREEN)
    LIGHTS(LIGHT2,BLUE)
    WAIT(UNIT_TIME)    
    LOGDATA(DATA_SNAPSHOT,"after60sec")                                            
    LOGDATA(DATA_DELTA,"after60sec") 
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:BASELINE|TEXT:SIXTH10SEC")                
    LOGAPPEND("TEXT:VARIABLE|TEXT:ARENA1_ZONE1_GREEN|TEXT:ARENA1_ZONE2_BLUE")
    LOGAPPEND("TEXT:ARENA2_ZONE1_GREEN|TEXT:ARENA2_ZONE2_BLUE")
    LOGRUN()
    INVOKE(WRITEDATA,1)

In the above code the commands to the unit are similar to the first group of commands at the top of ACTION BASELINE. These groups of commands are repeated at 10 second intervals, collating results data for each 10 second period.

LIGHTS(ALL,off)
    LOGDATA(DATA_SNAPSHOT,"total60sec")                                              
    LOGDATA(DATA_DELTA,"total60sec")
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:BASELINE|TEXT:TOTAL60SEC|TEXT:VARIABLE")       
    LOGAPPEND("TEXT:ARENA1_ZONE1|TEXT:ARENA1_ZONE2|TEXT:ARENA2_ZONE1|TEXT:ARENA2_ZONE2")
    LOGRUN()
    INVOKE(WRITEDATA,1)
COMPLETE

The final part of the ACTION BASELINE turns all the lights off and logs the data for the whole 60 second period.

Action WriteData

ACTION WRITEDATA                                               
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:ZONE_DISTANCES") 
    LOGAPPEND("ZONE_DISTANCES:A1,2 Z1,2")   
    LOGRUN()
    
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:ZONE_TIMERS")    
    LOGAPPEND("ZONE_TIMERS:A1,2 Z1,2")         
    LOGRUN()
    
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:ZONE_COUNTERS") 
    LOGAPPEND("ZONE_COUNTERS:A1,2 Z1,2")
    LOGRUN()
    
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:ARENA1|TEXT:ARENA2")
    LOGRUN()
    
    LOGCREATE("RUNTIME|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:|TEXT:TOTAL_ARENA_DISTANCES")
    LOGAPPEND("ARENA_DISTANCES:A1,2")
    LOGRUN()
COMPLETE

The ACTION WRITEDATA commands above tell the unit how to output the tracking data.

  • The first line of commands (which includes the LOGAPPEND line) specifies a line of data across the cells which specifies: 
    • the actual runtime this output was made 
    • heading text of ZONE_DISTANCES in cell 7 
    • data for sequential cells (from cell 8): the distances covered in the zones in both Arenas 1 and 2, measured in pixels. E.g. in cell 8 it will output the distance covered in Arena 1, Zone 1;  in cell 9 it will output distance covered in Arena 1, Zone 2; in cell 10 distance covered in Arena 2, Zone 1.
  • The second line of commands does the same as above but for ZONE_TIMERS, so specifying the time spent in each zone in both arenas.
  • The third line of commands is similar, but specifies the number of times the organisms, in each arena, enter each zone.
  • The fourth line specifies the runtime in the first cell and the heading text 'ARENA 1' in cell 8, heading text 'ARENA 2' in cell 9.
  • The final line above (5th) specifies the runtime in cell 1, heading 'Total_ARENA_DISTANCES' in cell 7 and the total arena distance moved in each arena in the 2 subsequent cells.
  • LOGRUN then tells the unit to output the data specified in the previous LOGCREATE lines (or those written subsequent to the last LOGRUN command).
  • Complete signifies this ACTION is finished.
Top

Script download

Here you can download the results 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: data_demo.zs . You will also need to save the assets (used in the script) into the unit's Asset directory. Make sure that the name of the assets exactly matches the name you use in the script (upper and lower case).

Script download: data_demo.zs

Asset download: test2_arenas2w    arenas2l

Top

Run the demo service

Build as a service - Once written, the zanscript is built (.zex file) and loaded on the Settings page in one of the 20 slots a service.

Run the demo service - The experiment can now be operated from the home page. In the following video example the demo script was run with 2 fake fish.

Baseline video

The 'Baseline' video, recorded during a test run, shows how two fake fish were moved during the Results data demo service. You will see that both fish moved from zone to zone together, but each time the colour stimuli changed Fish 2 moved more than Fish 1 in one of the zones.

Top

Results data file

The image below illustrates how the results data file details how the data was collected in 10 second periods for each fish: the distance travelled in each zone; time spent in each zone; a count of number of times each zone is entered. 

You may download the full results data file as a .csv file by clicking on the link here.

Screen Shot 2018 04 17 At 17 10 28
A snapshot of the results data illustrating the data captured during one 10 second period.
Top

Script variation

The data demo script described above was for 2 arenas, with 2 fake fish. The demo script below, data_demo_1_fish.zs, has been altered so that it is for just one fake fish, swimming over two zones. If you download the script you will see that the auto reference has been modified to 0 - SET(AUTOREF_MODE,0); and in the LOGCREATE (and subsequent LOGAPPEND) lines all references to Arena1 and Arena2  have been deleted.

Variation script download: data_demo_1_fish.zs

Asset download:  test2_arenas2w