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 detector 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.


Example assets for the AD unit

These assets are specific to zebrafish: A range of assets/bitmap images are included and referenced in the demo scripts for the Zantiks AD unit.

The following images illustrate several different detection setups in the Zantiks AD unit for zebrafish.


operant5hole.bmp, is a detector zone asset which loads 7 distinct zones corresponding to the 5 aperture insert and food magazine insert supplied with the system. Each colour is mapped against the central colour grid which is read from left to right, starting top left. The system uses these colours to assign detectors a number that will then be used in writing a script. In this example, the light blue square references detector1, the red square is detector 2 and so on.

Fully_zoned_operant5hole.bmp. This asset is similar to the operant5hole.bmp, with the centre open field set as a zone.
Asset for 2 lengthwise arenas/zones in the AD.
Asset for 2 widthwise arenas/zones in the AD.
Asset for 3 widthwise arenas/zones in the AD.

There may be times when the asset you have does not quite match up your AD unit's arena set and you will need a new asset.

When you first check a script, you should also check that the arena and zone assets in the script locate the arenas and zones in the places you expect. To do this:

  1. Load your tank/cage with its inserts in the chamber
  2. Click on the service that you want to run
  3. Go to the Live video page, click on Run
  4. Click on Advanced settings
Screen Shot 2019 10 03 At 16 11 02

The screen is now showing the advanced controls, they are displayed in boxes in the 'Control & status' panel located at the bottom of the page. If, for example, you are checking that the arenas asset in a service, correctly lines up with your arena set up in the tank, click Arenas to display all the arenas in different colours on the screen. Check that the different colours fill each arena and don't overlap into another arena.

If the assets don't match up with your tank set up, take a photo of the arena without a display showing. For example, if you have the arena asset showing, click Arenas again to remove the display. Then:

  1. Click on Capture image at the bottom of the Control Console.
  2. Navigate to the Media directory (via the home page).
  3. Download the capture.jpg file and email this this file to us; making sure not to change the format of the file when emailing it.
  4. We will then send you a .bmp file which you need to upload into the Assets directory.

Assets for the MWP unit

Before tracking any model organisms in the MWP unit you need to upload an arena definition file (arena asset) into the MWP's Assets directory. If you are tracking animals in zones, you will also need a detector asset which is based on the arena asset. In order to acquire these assets you need to make a .jpg inside your MWP unit using the calibration plate provided with your MWP unit. To do this:

  1. Place the calibration plate into the MWP unit's chamber on the diffuser stand. Ensure the plate fits snugly on the diffuser stand, and that the stand fits neatly into the recessed area at the bottom of the chamber. If the diffuser stand can move at all in the recessed area, push the diffuser stand to the left side and to the back. Similarly, if the calibration plate can move at all in the diffuser stand, push the plate (whilst in the diffuser in the chamber) to the left and to the back. See images.
  2. Useful Tip! Make a mark on one end of the diffuser stand and make sure you always insert the stand into the chamber with the marked end at the front. Always ensure you insert a multi-well plate the same way round.
  3. Go to the Live Video Display page and click on 'Capture image' underneath the image.
  4. Navigate to the Media directory.
  5. Download the 'capture.jpg' file and email this this file to us; making sure not to change the format of the file when emailing it.
  6. It is also beneficial to repeat this process for any multi-well plates you will be using for your experiments.
  7. Once we have the .jpg files we will then send you a .bmp file which you need to upload into the Assets directory. See images A1, A2, A3, A4 below for examples of arena assets and detector assets.
Asset Bits 2
1. Use the calibration plate and diffuser stand provided
Assembled Asset Bits
2. Place the calibration plate on the diffuser stand
Cal Plate In Unit
3. Place the diffuser stand, with the calibration plate, into the recessed area in the MWP's chamber, ensuring the four legs fit inside the recessed area
Other Asset Bits
4. Repeat process with the multi-well plate or petri-dish required for your experiments
Arenas 48
A1. Example of an arena asset for a 48-well plate
Arenas 24W
A2. Example of an arena asset for a 24-well plate
Kastureymazes Arenas
A3. Example of a Y-maze arena asset for Drosophila
Kastureymazes Zones
A4. Example of a Y-maze detector asset, showing four zones, for Drosophila

Using assets in a service

  1. Remember to save the assets in the Media directory in the MWP unit.
  2. Check that name of each asset matches exactly the name that you give the asset in the script, including upper and lower case letters.
  3. Make sure that you load the well-plate (which will probably be on a diffuser stand) the right way round into the MWP unit's experimental chamber - it needs to match the way the well-plate was loaded when the asset was taken.
  4. Push the diffuser stand to the left and back of the chamber; push the wellplate (in the stand) to the left and back of the chamber.
  5. Choose (click on) a service that loads the relevant arena asset. Go to the Live video display page, click on 'advanced controls' and click on arenas. This will display the arenas asset and enable you to check that the correct arena is chosen and whether the diffuser stand and well plate are correctly placed in the recessed area in the chamber. The image below (A6) shows you the misalignment between the arenas asset and the wellplate, when the stand and wellplate are not pushed in place.
Screen Shot Mwp Arena Asset Fits
A5. Live video display of MWP showing the arena asset loaded for correctly located 24 wellplate.
Screen Shot Mwp Arena Asset Plate Needs Adjustment
A6. Live video display of MWP showing incorrectly located wellplate - the wellplate (and diffuser stand) need to be pushed to left and back in experimental chamber

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 detector 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.