Zanscripts & services

In order to run an experiment in a Zantiks unit you need to write a script in Zantiks's proprietary software language, zanscript, and then build this script, so that it becomes a .zex file, which you can then upload onto the unit as a service.


Zanscript Directory

The Zanscript link, located at the bottom centre of the Zantiks Control Console page, brings up the Zanscript directory. This page lists all of the zanscripts saved on the unit. The demo scripts and any newly created or uploaded scripts are accessed here.

Screen Shot 2019 06 17 At 15 26 47
The Zanscript directory

From the Zanscript directory you can edit and delete zanscripts, create new scripts or upload zanscripts by clicking Choose Files at the top right of the page.


Explore a test script

Using the Edit button next to the script’s name takes you to the Zanscript Online Development environment, where you can make changes to the scripts.

The following are examples of a pre-loaded sample script in the Zanscript Online Development environment, illustrating how demo scripts can be annotated with descriptions of each command. The comments always follow a hash sign and will appear in brown text on this page.



Create a new script from a demo script

When learning to write a new script, it is often easiest to use parts of scripts from the demo scripts we provide. To ensure no permanent changes are made to the demo scripts, copy the text of a demo script into a new script file.


  1. From the Zanscript directory page, click Create New, enter a new file name and click Create file.
  2. This brings up the Zanscript Online Development page and a scripting box.
  3. You can write an entirely new script, or copy and paste elements from other demo Zanscripts.
    • The script will not autosave as you write. Take care to occasionally save at regular intervals.

Once familiar with some of the demo scripts, using amended commands in newly written scripts is recommended. Script amendments can include:

  1. Trial times: DEFINE commands can be edited to lengthen or shorten trials within the experiment.
    • For example, inter-trial interval times or data collection time bins can be changed.
  2. Types of stimuli: The colour, shape or style of the stimuli may be edited.
    • For example, a square shape on the built-in screen may be moved to a different location on the screen, changed in size, or replaced with an image.
  3. Stimulus exposure: The number of times aspects of the experiment can be performed by the system.
    • For example, repeating a stimulus exposure 8 times.

This video illustrates how to write a script, demonstrating the process with the Lights demo script.


Create and load a new service

  1. Once the script is complete, click the Build button. This can be found at both the top and bottom of the page.
  2. This saves and compiles the script and brings up the Zanscript Compiler page. The compiler page details any errors or warnings found in the script. It also tells you whether the build is successful or not.Compiler-page.png#asset:199
  3. A "long line warning" will appear if your script has notes. This does not affect the script and can be ignored.
  4. The Edit/Rebuild link at the bottom of the page will take you back into the script.
  5. If the script has built successfully, navigate to the home page using the Home link at the bottom of the page.
  6. To upload a new service, navigate to the Settings page from the administration section of the Control Console. The 20 numbered slots below the Zanscript shortcuts heading are used to load scripts to the Home page. Type the script's name (e.g., aversionlearninggreen) in the number box chosen to set the new service, and click Set.
    1. Please note: you may need to wait a few minutes to allow the system time to build the zanscript as a .zex file.
  7. The system will bring up a new page indicating a successful or unsuccessful link.
  8. Navigate back to the Control Console page, where the new ‘service’ is seen under the relevant slot. The new service is now ready to run!

Download a script

If you want to share a script with someone you can download the .zs file from the Zanscript directory. We recommend that you are using the Chrome web browser as this will allow you to download the file without changing the format.

To download a zanscript 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.)

Screen Shot 2019 10 17 At 09 41 04
1. Right click on the script and a box will pop up, choose option 'Save Link As....'
Screen Shot 2019 10 17 At 09 42 38
2. Choose the location you want to save the script, click on Save

Assets directory

Assets are bitmap files used to assign detection arenas for tracking or create visual stimuli on the screen. These files need to be uploaded into the Assets directory (this is found in the 'Administration section' at the bottom of the Control Console page) on the Zantiks unit in order for your script to execute correctly.

In a script which tracks animals in more than one arena, an arena asset is needed. To collect data in specified 'zones' within the arena, a zone asset is needed. When tracking one animal within the unit (e.g., 1 adult zebrafish in the AD unit's tank) an arena asset is not necessary as the entire tank is assigned as one arena by default.

Please note: images to be used on the AD unit's side screen need to be adapted as described in the Creating images for the side screen section on the Side screen demo page.


Building assets

In order to build automated assets, you will first need to calibrate you system. Detailed instructions on how to do this can be found in the calibrating your Zantiks unit manual

Once you have successfully calibrated your system you can start to build your own assets. Instructions on how to do this plus the necessary script downloads can be found in the following manuals:

Asset building in the MWP unit

Asset building in the AD unit

Asset building in the LT unit


Edit a service

If at any time you want to change any of the elements in the ‘service’/experiment go back to the Zanscript directory page:

Screen Shot 2019 04 05 At 14 56 41
Zanscript directory
  1. Click on the Edit button for the relevant experiment's script.
  2. In the experiment’s Zanscript Online Development page, make the script edits and click on the 'Build' button.
  3. This will update the Zanscript and the ‘service’, so that when you next run this ‘service’ it will take into account your changes.

Run a service

To run a service go to the Zantiks Control Console.

Zantiks Control Console Screenshot
Zantiks Control Console showing service 2, detector_zone_demo, is the selected 'Current service'
  1. Click on the ‘service’ that you would like the unit to run. The name of the service should appear as the ‘Current service’ at the top of the page.
  2. Click on the ‘Live Video’ button found at the bottom centre of the Control Console page to see a live video of the test environment. The clock at the bottom of the live video screen shows GMT (Greenwich Mean Time). When no service is running in the unit, the bottom centre shows the status of the unit as *IDLE*. See the screenshot (below).
  3. Click the ‘Run’ button at the bottom right of the Live Video Display page to start the experiment. Note that the system's status notice will read *RUNNING* in a pink bar. A stopwatch on the live video will change to show the running time of the experiment in seconds.
  4. To stop the experiment at any time, click the ‘Stop’ button at the bottom right of the screen. This terminates the experiment. Clicking ‘Run’ again starts the experiment from the beginning. There is no pause button.

Zantiks Live Video Display page

The Live Video Display page gives you a live feed of the experimental chamber. There are some advanced controls which enable you to check that the correct arena or zone assets are loaded in your script. First you need to select the service you want to use on the Home page, navigate to the Live Video page and then click 'Run'. The script will load and then you can check the assets are correct. (N.b. if you click to check the arena and zone assets before running the service, the assets loaded in the last experiment will be shown).

Checking the assets before you run a service is especially important with the MWP unit - you need to ensure that the arenas asset matches the wellplate. If the there seems to be a little misalignment the diffuser stand may need to be pushed to the left and to the back in the recessed area of the chamber, and that the wellplate needs to be pushed similarly in the diffuser stand.

Zantiks Live Video Display Screenshot
Zantiks Live Video Display page in the AD unit with a fake mouse

The screenshot above shows the Zantiks Live Video Display page during an experiment.

  1. The current service is called 'Mariana_memorytask' (ringed in blue oval) and it is 'RUNNING' (see 'RUNNING' is displayed in a pink box).
  2. The Live video screen shows a live image of the arena - at this point there are zones switched on (see colour blocks) and the unit is tracking a 'fake mouse'.
  3. The image displayed is small as the camera has been reprogrammed to accommodate a bigger animal, and the camera is taking 15 frames per second (see the line at the bottom of the image 'Target frame rate: 15FPS'. If a smaller animal is being tracked the camera is on its default setting and the live video displays a larger image and the camera takes 30 frames per second.
  4. The screen is showing the advanced controls - hence the link (ringed in red) says 'Hide advanced controls' - click on this link and you can hide the advanced controls.
  5. The five advanced controls are marked by the red arrows, if you click on the link boxes you can change the display on both the video recording (if a service is live and programmed to record one), and on the Live video screen accordingly:
  • Timestamp: click on this and the timestamp will not display.
    Lighting: click on this and the overlays (i.e. the visualisations of the zones currently programmed) will not appear.
    Arenas: click on this and the arena asset will appear.
    Zones: click on this and the zone asset will appear.
    Reset: click on this and the default settings will display - with timestamp and with overlays appearing when they are programmed to appear.

For descriptions of the Zanscript syntax visit the manual here.

For example demo scripts, with detailed notes, click here.

For Zanscript tutorials, click here.