This tutorial demonstrates how to use the LOG_STREAM commands to export multiple, separate data files.
The example used here exports raw xy data into a .csv results file separate from the processed data file (e.g., distance moved in arenas).
The script below demonstrates how to capture both types of data and export them into separate, easy to read .csv files.
We recommend that you first review the syntax page and the tutorial page for the LOGDATA, LOGCREATE AND LOGRUN commands.
Creating multiple data files within one script
There are 4 individual LOG STREAMS available to use in Zanscript. By assigning and 'calling out' individual LOG STREAMS within your script, you can allocate which data writes to the separate .csv files.
SET(LOG_STREAM,0) SET(LOG_STREAM,1) SET(LOG_STREAM,2) SET(LOG_STREAM,3)
SET(LOG_STREAM,#) commands are used in the script just prior to setting the structure of your data output (e.g., placed before the relevant LOGCREATE, LOGAPPEND and LOGRUN commands). They tell the system that the assigned log stream is now active and to write any following data collection commands to this active data file until a new log stream is set.
LOG_STREAM,0 is the default log stream. If you are not separating data files, it is not necessary to write this command into your scripts, as all data is reported to this log stream by default.
NOTE: It is recommended that the SET(LOG_STREAM,#) command is written prior to the AUTOREFERENCE() command.
LOGFILE(0,"name_of_data_file") LOGFILE(1,"name_of_data_file") LOGFILE(2,"name_of_data_file") LOGFILE(3,"name_of_data_file")
LOGFILE(#,"name_of_data_file") is used in conjunction with SET(LOG_STREAM,#) to change the name of the new, separate data file. The text written within the " " is added to the end of the default data file name. This command is used immediately prior to setting the log stream.
For example, if your service is called "my_experiment", the data file's name will begin with this name, followed by the date and time that the service was run (e.g., "my_experiment-20210912T104820.csv"). If LOGFILE(1,"XY_data") is used, the file's name is logged as "my_experiment-20210912T104820-XY_data.csv."
If you are not separating data files, a LOGFILE command is not necessary as the default data file name is simply the name of the service, dated and timestamped.
NOTE: It is recommended that the LOGFILE(1,"name_of_data_file") command is written immediately prior to the SET(LOG_STREAM,#) command.
Key commands to separate xy data from processed data:
LOGFILE(1,"XY_data") SET(LOG_STREAM_PERFRAME,1)
These commands set up the log stream for perframe data collection (i.e., XY coordinates). These commands come before any ACTIONs.
Once the XY data collection is initiated in the script, it will be collected continuously alongside any other requested data collection (e.g., distance travelled) and logged to the log stream requested in the SET(LOG_STREAM_PERFRAME,1) command. Perframe data is the only exception in using SET(LOG_STREAM,#) commands from above, as you will only need to activate the log stream to write your column headers and create your data structure format. (With other data types, you must activate the log stream you want the data to report to throughout the script.)
In the code example above, LOGFILE(1,"XY_data") is first labelling the data file 1 with the suffix XY_data and then SET(LOG_STREAM_PERFRAME,1) is instructing the software to report all XY data to log stream 1.
LOGCREATE("RAW_XY:A1-24")
This command structures the way the XY data is reported to the .csv file; similar to other data commands used within LOGCREATE. This example is writing XY data for all 24 arenas in a multi well plate.
SET(LOG_PERFRAME,ON) SET(LOG_PERFRAME,OFF)
These two commands are used to turn on and off the xy coordinate data collection. They should be written at the point in your script where you want data collection to begin and end. The LOGCREATE("RAW_XY:#") will need to be written in the script at some point before the SET(LOG_PERFRAME,ON) is introduced.
Full example script
DEFINE NUM_SAMPLES 10
DEFINE TIME_BIN 1
SET(TARGET_SIZE,2)
SET(DETECTOR_THRESHOLD,6)
SET(AUTOREF_MODE,MOVEMENT)
SET(AUTOREF_TIMEOUT,0)
DEFINE X_DRAWTRACKS 30011
DEFINE X_TRACKTIME 30016
LOGFILE(1,"XY_data")
SET(LOG_STREAM_PERFRAME,1)
****************************************
ACTION MAIN
SET(COUNTER1,COUNTER_ZERO)
LOAD(ARENAS,"a24.bmp")
LOGCREATE("TEXT:RUNTIME|TEXT:UNIT|TEXT:TEMPERATURE|TEXT:TIME_BIN|TEXT:ARENA")
LOGAPPEND("TEXT:A1|TEXT:A2|TEXT:A3|TEXT:A4|TEXT:A5|TEXT:A6")
LOGAPPEND("TEXT:B1|TEXT:B2|TEXT:B3|TEXT:B4|TEXT:B5|TEXT:B6")
LOGAPPEND("TEXT:C1|TEXT:C2|TEXT:C3|TEXT:C4|TEXT:C5|TEXT:C6")
LOGAPPEND("TEXT:D1|TEXT:D2|TEXT:D3|TEXT:D4|TEXT:D5|TEXT:D6")
LOGRUN()
SET(LOG_STREAM,1)
LOGCREATE("TEXT:RUNTIME|TEXT:X_A1|TEXT:Y_A1|TEXT:X_A2|TEXT:Y_A2")
LOGAPPEND("TEXT:X_A3|TEXT:Y_A3|TEXT:X_A4|TEXT:Y_A4")
LOGAPPEND("TEXT:X_A5|TEXT:Y_A5|TEXT:X_A6|TEXT:Y_A6")
LOGAPPEND("TEXT:X_B1|TEXT:Y_B1|TEXT:X_B2|TEXT:Y_B2")
LOGAPPEND("TEXT:X_B3|TEXT:Y_B3|TEXT:X_B4|TEXT:Y_B4")
LOGAPPEND("TEXT:X_B5|TEXT:Y_B5|TEXT:X_B6|TEXT:Y_B6")
LOGAPPEND("TEXT:X_C1|TEXT:Y_C1|TEXT:X_C2|TEXT:Y_C2")
LOGAPPEND("TEXT:X_C3|TEXT:Y_C3|TEXT:X_C4|TEXT:Y_C4")
LOGAPPEND("TEXT:X_C5|TEXT:Y_C5|TEXT:X_C6|TEXT:Y_C6")
LOGAPPEND("TEXT:X_D1|TEXT:Y_D1|TEXT:X_D2|TEXT:Y_D2")
LOGAPPEND("TEXT:X_D3|TEXT:Y_D3|TEXT:X_D4|TEXT:Y_D4")
LOGAPPEND("TEXT:X_D5|TEXT:Y_D5|TEXT:X_D6|TEXT:Y_D6")
LOGRUN()
LOGCREATE("RUNTIME|RAW_XY:A1-24")
SET(LOG_STREAM,0)
AUTOREFERENCE()
SET(LOG_PERFRAME,ON)
SET(X_DRAWTRACKS,1)
INVOKE(SAMPLE,NUM_SAMPLES)
SET(LOG_PERFRAME,OFF)
COMPLETE
****************************************
ACTION SAMPLE
SET(COUNTER1,COUNTER_INC)
LOGDATA(DATA_SNAPSHOT,"begin")
WAIT(TIME_BIN)
LOGDATA(DATA_SNAPSHOT,"end")
LOGDATA(DATA_DELTA,"end")
LOGCREATE("RUNTIME|APPARATUS_ID|TEMPERATURE1")
LOGAPPEND("COUNTER1|TEXT:DISTANCE|ARENA_DISTANCES*")
LOGRUN()
COMPLETE
Script explanation
DEFINE NUM_SAMPLES 10 DEFINE TIME_BIN 1
The two DEFINE commands detail the time in seconds for the terms DEFINE NUM_SAMPLES and DEFINE TIME_BIN,1 where they are used 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 'movement' 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 you to change the length of time the traces appear on the screen before disappearing.
LOGFILE(1,"XY_data") SET(LOG_STREAM_PERFRAME,1)
- LOGFILE(1,"XY_data") sets up the separate data file for xy data and names it "xy_data". This will be in the title of the output file. LOGFILE,0 is the system's default for processed data.
- SET(LOG_STREAM_PERFRAME,1) sets the system to ready itself to output xy coordinate data per frame into its own .csv file.
ACTION MAIN SET(COUNTER1,COUNTER_ZERO) LOAD(ARENAS,"a24.bmp")
- SET(COUNTER1,COUNTER_ZERO) labels a counter as counter 1 and asks the system to begin the counter at 0.
- LOAD(ARENAS,"a24.bmp") loads the bitmap file for the 24-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:RUNTIME|TEXT:UNIT|TEXT:TEMPERATURE|TEXT:TIME_BIN|TEXT:ARENA")
LOGAPPEND("TEXT:A1|TEXT:A2|TEXT:A3|TEXT:A4|TEXT:A5|TEXT:A6")
LOGAPPEND("TEXT:B1|TEXT:B2|TEXT:B3|TEXT:B4|TEXT:B5|TEXT:B6")
LOGAPPEND("TEXT:C1|TEXT:C2|TEXT:C3|TEXT:C4|TEXT:C5|TEXT:C6")
LOGAPPEND("TEXT:D1|TEXT:D2|TEXT:D3|TEXT:D4|TEXT:D5|TEXT:D6")
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 24-well plate.
- LOGRUN tells the unit to now output the above data into the .csv file.
SET(LOG_STREAM,1)
LOGCREATE("TEXT:RUNTIME|TEXT:X_A1|TEXT:Y_A1|TEXT:X_A2|TEXT:Y_A2|TEXT:X_A3|TEXT:Y_A3") LOGAPPEND("TEXT:X_A4|TEXT:Y_A4|TEXT:X_A5|TEXT:Y_A5|TEXT:X_A6|TEXT:Y_A6")
LOGAPPEND("TEXT:X_B1|TEXT:Y_B1|TEXT:X_B2|TEXT:Y_B2|TEXT:X_B3|TEXT:Y_B3") LOGAPPEND("TEXT:X_B4|TEXT:Y_B4|TEXT:X_B5|TEXT:Y_B5|TEXT:X_B6|TEXT:Y_B6")
LOGAPPEND("TEXT:X_C1|TEXT:Y_C1|TEXT:X_C2|TEXT:Y_C2|TEXT:X_C3|TEXT:Y_C3") LOGAPPEND("TEXT:X_C4|TEXT:Y_C4|TEXT:X_C5|TEXT:Y_C5|TEXT:X_C6|TEXT:Y_C6")
LOGAPPEND("TEXT:X_D1|TEXT:Y_D1|TEXT:X_D2|TEXT:Y_D2|TEXT:X_D3|TEXT:Y_D3") LOGAPPEND("TEXT:X_D4|TEXT:Y_D4|TEXT:X_D5|TEXT:Y_D5|TEXT:X_D6|TEXT:Y_D6")
LOGRUN()
- SET(LOG_STREAM,1) is telling the system the following commands are to be logged to the LOGFILE,1 (as set above). The logged data "stream" #1 will be xy data.
- The LOGCREATE, LOGAPPEND and LOGRUN commands are now writing writing heading labels onto the second separate xy data file that will be exported as set by SET(LOG_STREAM,1).
LOGCREATE("RUNTIME|RAW_XY:A1-24")
- LOGCREATE("RUNTIME|RAW_XY:A1-24") - this LOGCREATE command specifies the content for a row of data and outputs it into the .csv file. In this case, on the line below the headings, it reports the time the xy data was collected, followed by the xy coordinates for each of the 24 wells at that time point.
SET(LOG_STREAM,0) AUTOREFERENCE() SET(LOG_PERFRAME,ON)
- SET(LOG_STREAM,0) is telling the system to begin logging data to LOGFILE,0. The logged data "stream" 0 will be processed data.
- AUTOREFERENCE() creates a reference image of the well plate prior to invoking the trials. It is needed for tracking.
- SET(LOG_PERFRAME,ON) begins the logging of xy coordinate data for each frame. This command needs to be written into the script before any trials commence (i.e., when the tracking begins).
SET(X_DRAWTRACKS,1) INVOKE(SAMPLE,NUM_SAMPLES) SET(LOG_PERFRAME,OFF) COMPLETE
- 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 the trial beginning.
- 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.
- SET(LOG_PERFRAME,OFF) - ends the logging of xy data. This command needs to be written into the script after all the trials have ended.
ACTION SAMPLE
SET(COUNTER1,COUNTER_INC)
LOGDATA(DATA_SNAPSHOT,"begin")
WAIT(TIME_BIN)
LOGDATA(DATA_SNAPSHOT,"end")
LOGDATA(DATA_SELECT,"begin")
LOGDATA(DATA_DELTA,"end")
LOGCREATE("RUNTIME|APPARATUS_ID|TEMPERATURE1")
LOGAPPEND("COUNTER1|TEXT:DISTANCE|ARENA_DISTANCES*")
LOGRUN()
COMPLETE
The ACTION SAMPLE processes data in 1 second time bins for multiple parameters:
- SET(COUNTER1,COUNTER_INC) is set to count this ACTION incrementally.
- LOGDATA(DATA_SNAPSHOT, "begin") logs the processed tracking data and calls this data "begin". The system then WAITs for a period of time in seconds DEFINEd as BIN at the top of the script.
- LOGDATA(DATA_SNAPSHOT, "end") makes another log of the tracking data after the TIME_BIN and calls this data "end".
- The following LOGDATA commands (DATA_SELECT,"begin") and (DATA_SELECT,"end") instructs the unit to calculate the difference between "begin" and "end".
- The final series of LOGCREATE, LOGAPPEND and LOGRUN() commands specify the content for a row of data and outputs it into the .csv file. In this case:
- The units runtime can be input using the command RUNTIME
- The unit's ID
- The current temperature at the time this data was collected.
- COUNTER1 will input number of the time bin
- The variable being measured is then written in TEXT (i.e., ZONE_DISTANCES)
- ARENA_DISTANCES* asks the system to calculate the distance travelled for all the arenas.
Script download
To download the xy_multiple_data_files 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: xy_multiple_data_files.zs
Assets
You will need to upload the appropriate asset into the Asset directory on your Zantiks Control Console and ensure the correct asset name is in the LOAD(ZONES,"name_of_asset") command in the script.
See the Calibrating your Zantiks unit page and Asset building in the AD unit page or Asset building in the LT unit page for details on how to create assets customised to your system.
