Zanscript syntax


All the experiments that run in a Zantiks unit are written in Zanscript - a proprietary Zantiks scripting language that is easy to learn and edit to experimental needs.

Top

Background to Zanscript syntax

Scripts are built on the unit to make services, which are then run on the unit. Scripts may refer to bitmap files that need to be present in the assets directory on the unit on which the service is being run. Zantiks units are supplied with sample scripts (and in some cases pre-written setting scripts) and relevant assets.

We supply ‘fake fish on sticks’ to enable users to run test experiments with this fake organism(s) to help build their knowledge of how the system works, test their scripts, and test the tracking before using the unit in real experiments. Please refer to the relevant System run through post set up document. Example videos of how test experiments can work with ‘fake fish’ are available on the website (www.zantiks.com/ad-tutorials).

All the sample scripts follow the same format. Firstly there maybe be some DEFINE and INCLUDE directives that set the script up. This is followed by the ACTION MAIN, and then other ACTIONS, both of which include commands and functions.

Once a script is fully written it needs to be ‘Built’ to create a .zex file. This compiles the script (and all the “INCLUDE” settings) into a useable format (a ‘service’, *.zex, for the unit). Press the ‘Build’ button at the top or bottom of the Zanscript page. You can then load the experiment as a service on the unit. All .zex files are held in the ‘Services Directory’ which can be accessed from a link on the Home page.

Zanscript is a proprietary Zantiks script language. There are three different types of syntax - directives, commands and functions - which are listed below with a brief explanation of how they are be used.

Before actual experimentation please do test your new scripts thoroughly with a ‘fish-on-a-stick’ and learn from the sample scripts provided.

Top

Directives

DEFINE

allows you to define new variables, and assign them values, and these can then be called upon later in the script.

This directive can be used to designate a value for terms used in the experiment (e.g., terms used for time variables, such as time in seconds, or number of times to repeat an element of the script, or light stimuli).

E.g., when defining the name used in the script to describe stimuli types that appear on the screen:

DEFINE CIRCLE 1

This example directive enables you to use the word circle in the script instead of having to remember that the number 1 will create a circle shaped image stimulus on the screen.

DEFINE SQUARE 2

This example directive enables you to use the word square in the script instead of having to remember that the number 2 will create a square shaped image stimulus.

DEFINE SPRITE 5

This example directive enables you to use the word sprite in the script instead of having to remember that the number 5 will instruct the program to look for a bitmap. You will need to name the image/bitmap (as it is named in the assets folder) later in the script. N.b. sprite is a term used in computer graphics, and is a two-dimensional bitmap that is integrated into a larger scene. Using sprites allows us to display any image anywhere on the screen).

DEFINE SPRITE_IMAGE 520

This example directive needs to be in the script if you have a sprite image.

INCLUDE

allows you to import the content of one external script to be included as part of the script. This directive can be used to include a setting script (e.g. a setting script which contains appropriate settings for an experiment).. Ensure the setting scripts are loaded on your unit. (The only exception is ZSYS which is preloaded, but not visible, on all Zantiks units, but is to be INCLUDE ZSYS at the outset in all scripts.)

Top

Commands

Commands control where one goes when in the script.

ACTION

is the name for a section of the program that can be used once, or many times. Our sample scripts have an ACTION called MAIN, and it is the first action in the script, and is typically run once. When naming an action, do not choose a word that has been defined already in the Zanscript programming language, e.g. RED, BLUE, GREEN, LIGHTS , FEEDER etc. You can create a version of the word - e.g. MMRED, LIGHT6 etc

COMPLETE

is the command to indicate the end of the preceding ACTION.

INVOKE

is the command to call up other ACTION to be run. It can also signify how many times an ACTION is to be run.

E.g.

INVOKE(ACT1,4)

would run the ACTION called ACT1 4 times. The script would then go to the line below.

INVOKE(ACT1,TRIALS)

would run ACTION called ACT1 4 times if there was this directive earlier:

DEFINE TRIALS 4

The script would then go to the line below.

DETECTOR

allows the script to call up other actions if the detector is triggered. If the detector is not triggered then the ACTION continues after the following WAIT statement has been completed. After the triggered ACTION has been run the script returns to after the WAIT following the DETECTOR commands.

SELECT

allows one to choose between 2 options with defined probabilities.

E.g. 1

SELECT (OUTCOME1,OUTCOME2)

Will choose randomly between going to (the ACTION) OUTCOME1 or OUTCOME2.

E.g. 2

SELECT (OUTCOME1,OUTCOME2or3,0.333)

ACTION OUTCOME2or3

SELECT(OUTCOME2,OUTCOME3)

COMPLETE

Will select between OUTCOME1 with a probability of 0.333 and randomly select between either OUTCOME2 and OUTCOME3 with a probability of 0.666

SELECT

tells the system to select the two ACTIONs written in brackets - () - and detailed in ACTION below - to run randomly.

E.g

SELECT(GREEN_LEFT,GREEN_RIGHT)

This command selects the first ACTION (i.e. GREEN_LEFT in this case) 50% of the time, and the second ACTION (following the comma i.e. GREEN_RIGHT) 50% of the time. These 2 ACTIONS would then each need to be defined in their own ACTION section below. This command is useful if you are running a two choice discrimination test, and want to include an ACTION (eg DETECTOR) that randomly selects the position of the stimulus colours.

Top

Functions

Functions are executed as they are encountered in the script.

AUTOREFERENCE(0)

attempts to automatically create an image from the camera without the organism present. This image is stored as autoref.bmp in the assets directory. The image is made with the assumption the organism(s) is(are) dark on a lighter background, and that it(they) move. Its mode of operation can be changed with parameters set by the SET function.

In the autoreference mode the system, over a set period of time (as detailed in the SETSINGLEZFISH script) will take images, and compile them so that the organism can be tracked during the experiment.

WAIT

details a time in seconds for the script to stay. You can DEFINE the number of seconds in a previous DEFINE command.

E.g.

WAIT(10)

will wait 10 seconds before moving on.

WAIT(HABITUATION)

will wait for 8 seconds if previously there is a command:

DEFINE HABITUATION 8

Screen Coordinates Vn3 2
This illustration depicts the coordinates (in pixels) for each corner, centre point of each edge and the middle point of the unit's screen, set inside the edges of the tank that sits on top of the screen.

SETLIGHT

sets the type of visual stimulus to be displayed, as well as its location in the screen - see the illustration above detailing Screen coordinates on Zantiks unit. For ‘sprite’ images (.bmp) you can also set the size.

E.g.

SETLIGHT(LIGHT1,SQUARE,1475,100,140)

sets LIGHT1 as a geometrical square of light to be displayed on the coordinates 1475,100 within the screen, with the centre of the square located at the coordinate 1475,100. The size of the square is set at 140 pixels.

SETLIGHT(LIGHT2,SPRITE,800,200,0)

specifies that LIGHT2 is a “sprite” bitmap image to be displayed on the screen coordinates 800,200, at its native size (as the next value after the comma is 0). The defined ‘LIGHT2” can then be controlled using the LIGHTS command (see below). One can change the size of the sprite by changing the final value in the SETLIGHT command to the required size (larger dimension) in pixels of the sprite.

SETLIGHT(LIGHT1, square, 800,500,1600)

Would make LIGHT1 the size of whole screen.

LIGHTS

can turn lights on and off, and specify different colours. It can refer to the overhead lights (LIGHT16) or any lights or images that have been set to appear on the screen using the SETLIGHT function.

E.g.

LIGHTS(LIGHT1,RED)

would turn LIGHT1 red. You would have described the location of LIGHT1 earlier in the script using the function SETLIGHT.

LIGHTS(16,BLUE)

would turn the overhead light (the house light) blue. There are 7 overhead lights defined in the system - red, green, blue, cyan, magenta, yellow, white.

LIGHTS(ALL,OFF)

turns all lights off and is a useful function to use as, when used, it ensures an experiment, or section of an experiment, begins with no stimuli on.

PANLIGHT

will make a sprite image scroll across the screen from the position it started at (i.e. from its original location as detailed in a SETLIGHT function or from the position it moved to following the previous PANLIGHT function) to the position detailed after the PANLIGHT command:

E.g.

PANLIGHT(LIGHT8,100,500,8)

will make the image move, from its starting position (as detailed above) to the position on the screen defined here (100,500), over a period of 8 seconds.

PANLIGHT(LIGHT8,100,500,SCROLLTIME)

will make the image move, from its starting position (as detailed above) to the position on the screen defined here (100,500), moving for the pre-defined time SCROLLTIME.

LOAD

This command details the asset / bitmap to load (which must be stored in the Assets Directory folder). It can include further instructions in what context to use the asset - i.e. as a DETECTOR or ARENA.

E.g.

LOAD(DETECTORS,”fullyzoned_5hole”)

This function will load the asset called “fullyzoned_5hole” and detect any movement in the highlighted zones.

LOAD(ARENAS,”arenas4l”)

This function will load the asset called “arenas4l” which indicates the number and shape of different arenas that are set up for tracking the model organisms.

LOAD(SPRITE_IMAGE,"8:danio_small")

This function will load the bitmap called “danio_small” as LIGHT8, in this example because of a previous command - SETLIGHT(LIGHT8,SPRITE,0,500,0) - which sets the sprite image's beginning position, sprite mode and size on the screen. For full example see webpage [https://zantiks.com/ad-tutorials].

VIDEO

starts the video recording for the time in seconds specified in brackets, saving the video with the name detailed in the parenthesis, “ ”

E.g.

VIDEO(15,”videotest”)

will record 15 seconds of video into the Media Directory file with a name starting “videotest” (and then with a time and date). The video recording has been designed to provide a useful record of short parts of the experiment, for reference only. The system prioritises running the experiment and processing the results live, and then will try and make the requested video. This means that one can have dropped frames, and it is possible the overlay of the screen onto the camera image can ‘drift’ over time. The time written into the video image will be correct (i.e. the computer time at which the image was acquired from the camera).

As the computer records the experiment the video images are processed later on and combined with any asset images used. This can lead to a slight ‘drift’ between these two events.

The “videotest” footage can be found in the Media Directory, accessible from a link on the Home page.

SET

This is a function that can be used in many different ways. Some examples are given below.

Eg.

SET(AUTOREF_MODE,1)

sets the AUTOREFERENCE system to use brightness mode (the reference image is formed by using the brightest pixel seen by the camera in a particular position over the time of the autoreference procedure.

MODE,0 uses the the motion mode - appropriate only when there is one organism, and only one arena. MODE,1 is for more than one organism.

SET(AUTOREF_TIMEOUT,20)

sets the (maximum) time for the autoreference procedure.

SET(VOLTAGE_LEVEL,9000)

sets the voltage level to 9000 millivolts for the shocking output (socket CN5), for example in an aversion experiment.

SET(VOLTAGE4, 70)

sets 4th output pair (of 4) of CN5 to the set VOLTAGE_LEVEL for 70 ms.

SET(COUNTER1,COUNTER_ZERO)

allows you to count different elements of an experiment and record them accordingly in the pre-processed results data. E.g. the above example sets COUNTER1 to the value 0. There are 25 counters available, C0UNTER1 through to COUNTER25.

SET(COUNTER2,COUNTER_INC)

sets COUNTER2 to increment its value by 1.

SET(ACTIVITY_THRESHOLD,10)

is used in a mouse nosepoke experiment, this setting tracks any mouse nosepoke in a live detector zone. N.B. this tracking is in addition to the movement tracking of the mouse which is based loosely on the mouse’s centre of gravity.

FEEDER

tells the system to turn on the brass feeder mechanism, which can either be turned on to deliver some food (which will need to be preloaded in the dispenser) or to make a small movement which is not enough to deliver food, but makes a very similar noise/vibration to the feeding procedure.

E.g.

FEEDER(0)

tells the system to turn on the feeder mechanism, without dropping food.

FEEDER(1)

tells the system to turn on the feeder mechanism, to deliver one portion of food.

MOTORCOMMAND

controls the stepper motor that rotates the peristaltic pump, the feeder mechanism for powdered food and pellets, and the vibration of the MWP system.

E.g.

MOTORCOMMAND(“U0 D1000 M200”)

the numbers in the brackets - and written between inverted commas “” - indicate the rotation parameters:

'M' Number of Motor steps (e.g. 200, -50). 200 steps is a full 360 degree rotation

'D' Delay between motor steps (to set motor speed - should not be below 1000)

'U' Step mode (0-3, for full/half/quarter/eighth step modes)

'P' Pause, to set delay between motor movements (milliseconds)

LOG

writes text to the data file on a new line (with the time at the front).

E.g.

LOG(“this text”)

writes “this text” to the data file on a new line (with the time at the front).

LOGDATA

The system is keeping a continuous record of the current measure of various measure - e.g. distance travelled in each detector zone, number of visits to detector zones. Logdata allows one to record to memory the current values using the command below.

E.g.

LOGDATA(DATA_SNAPSHOT “begin”)

records information at this point of the script, and it is given the name ‘begin’. If the command was run again the data would be overwritten with the new current values.

LOGDATA(DATA_SNAPSHOT “end”)

records information with the name ‘end’.

LOGDATA(DATA_SELECT “begin”)

pulls the data from the named SNAPSHOT “begin” above.

LOGDATA(DATA_DELTA “end”)

calculates the change of parameter values between the DATA_SELECT snapshot and the DATA_DELTA snapshot.

LOGRUN()

writes the calculated parameter values as requested by the current LOGCREATE/LOGAPPEND statement.

LOGCREATE

specifies a format / contents for a line in the data output file. It can be used to create headers for columns, and for lines containing the data.

RUNTIME - writes the time a specified action occurs.

TEXT: | - leaves cell empty.

E.g. TEXT: example_text | - writes the text following the colon in the cell.

N.B., When writing a script, be aware that the system will only make sense of the first 78 characters in an expression. Therefore, if the text within the “ “ of a LOGCREATE command is longer than this, continue the expression on a new line with a LOGAPPEND command, and you can do this multiple times. If a command line is too long when you build the script, it will not build successfully and there will be an error for that long line of code. We have included notes in the sample scripts (they appear on a line of command after a #). These lines can generate a warning when you build the script, but the script still builds successfully (as text after the # is ignored).

LOGAPPEND

is an appendage to the line above. This is required as only the first 78 characters of a line are processed.

LOGRUN()

writes the data specified in the latest LOGCREATE line to the data file.

LOGFIELD

Prepares in the memory the instruction that follows in brackets. The number indicates the cell - NB number the cells incrementally from 1 when 1 is the third cell in the data output line. Anything written between inverted commas, “ ” , will be written in full (a space left between “ “ indicates leave cell empty).

E.g.

LOGFIELD(1,”TRIAL_INITIATED”)

prepare in the memory to write words (i.e. cell heading) - TRIAL_INITIATED - in the third cell in the data output line.

LOGFIELD(2,”start_time”)

prepares in the memory to write words (i.e. cell heading) - start_time - in the fourth cell in the data output line.

LOGFIELD(1,COUNTER1)

prepares in the memory to write the number of counts COUNTER1 has got to at this stage in the script in the third cell in the data output line.

LOGFIELD(2,RUNTIME)

prepares in the memory to write the actual runtime in the script at that moment in the fourth cell.

LOGFIELD(COMMIT)

tells the system to write the contents of the fields as specified by earlier LOGFIELD commands (after the previous COMMIT). It then clears the contents of the fields.