Before starting an experiment in a Zantiks unit you need to make sure that you have the correct tracking settings for your model organism.
This tutorial walks you through the process of adjusting the tracking settings in your scripts so that the model organisms you are studying are tracked reliably.
The tracking settings are comprised of six to seven SET functions located at the beginning of the script which tell the unit how to find and track the organism/s in the arena/s.
First of all choose the standard tracking settings for the model organism that best fits the size and shape of your organism, as shown below for adult zebrafish, larval zebrafish, adult Drosophila, Daphnia. If in doubt, please contact us with details of your organism.
Next, check which parameters for the SET functions best track your organism by including the values from the standard tracking settings in a simple script, and watching on the 'Live video' screen how reliably the 'crosshairs' track your animals.
Your simple script could be based on the locomotor data demo. Using this script overwrite the SET values listed below for your model organism, or the organism that matches it most closely in size.
Tracking settings in the AD unit
SET(AUTOREF_MODE,1) SET(AUTOREF_TIMEOUT,20) SET(DETECTOR_THRESHOLD,2) SET(SEARCH_DISTANCE,50) SET(SEARCH_STEP,7) SET(FILTER_RADIUS,15)
If you have a larger fish, for example a killifish which is approximately 3-5cm, try keeping the DETECTOR_THRESHOLD at 2, but increasing SEARCH_DISTANCE to 64, SEARCH_STEP to 8 and FILTER_RADIUS to 25.
Tracking settings in the MWP units
SET(TILE_SIZE,5) SET(AUTOREF_MODE,1) SET(AUTOREF_TIMEOUT,10) SET(DETECTOR_THRESHOLD,6) SET(SEARCH_DISTANCE,10) SET(SEARCH_STEP,3) SET(FILTER_RADIUS,3)
SET(TILE_SIZE,5) SET(AUTOREF_MODE,1) SET(AUTOREF_TIMEOUT,30) SET(DETECTOR_THRESHOLD,10) SET(SEARCH_DISTANCE,9) SET(SEARCH_STEP,3) SET(FILTER_RADIUS,6)
SET(TILE_SIZE,5) SET(AUTOREF_MODE,1) SET(AUTOREF_TIMEOUT,30) SET(DETECTOR_THRESHOLD,7) SET(SEARCH_DISTANCE,7) SET(SEARCH_STEP,2) SET(FILTER_RADIUS,2)
Tracking settings in the LT unit
SET(AUTOREF_MODE,1) SET(AUTOREF_TIMEOUT,20) SET(DETECTOR_THRESHOLD,2) SET(SEARCH_DISTANCE,36) SET(SEARCH_STEP,6) SET(FILTER_RADIUS,12)
Notes on the SET functions
The Zanscript includes a default TILE_SIZE of 10 which is the TILE_SIZE used for an average sized zebrafish (2-3cm). If you are using larger or smaller animals you need to include this function to reset the TILE_SIZE - smaller animals such as larval zebrafish and Drosophila require a smaller TILE_SIZE and vice versa.
These two functions tell the unit how to take an autoreference image.
The AUTOREFERENCE() function attempts to automatically create an image from the camera without the organism present. This is done by filming for a period of time (as detailed in the SET(AUTOREF_TIMEOUT, #) command). This compiled 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 during the filming period. Tracking is achieved by looking for significant differences of suitable size and strength between this 'empty' image and the current video image.
We recommend that you always include SET(AUTOREF_MODE,1), the value of 1 here means that the reference image will be based on brightness, and it can be used for one or many organisms.
The SET(AUTOREF_TIMEOUT,10) tells the unit to take the reference image over a period of time, in this case 10 seconds. If your animals are unlikely to move much you would increase this setting to a time during which you are confident some movement will have been made.
Remember, you will need to include the function AUTOREFERENCE() in ACTION MAIN at the very start of your experiment which tells the unit to take the reference image (using the two SET functions detailed above).
The two SET functions above should not need altering from those you have for the standard sized organism.
You are most likely to tweak the parameter of this function, the FILTER_RADIUS. If the value is too low the crosshair jumps around the model organism or may detect 'noise' and jump around the arena. If the parameter is too high then tracking may be intermittent and stationary animals may not be found.
The DETECTOR_THRESHOLD is the other parameter you are likely to change. If the DETECTOR THRESHOLD is too high for the size of the organism, it will find nothing, and you will see no crosshair, if it is too low the unit detects 'noise' and the crosshair jumps around the arena/s.
Testing the SET functions
Before starting any experiment with animals that you have not tracked before in the unit, check that you are using the correct values in the SET functions.
- If you are using the MWP, once your organisms are singly-housed in a well plate, place them on the diffuser stand in the MWP unit, making sure that the diffuser stand is securely in place in the recessed area, and the well-plate fits snugly into the stand.
- Open your test script in the Zanscript directory (click on Edit) and check that your script:
- has the values in the SET functions for that organism that is close in size to your animals (contact us for the best SET values to use if you are not sure)
- includes the arena asset that matches the well-plate or AD tank arena set up you are using (for more details see the 'Assets for the AD/MWP' sections in the Zanscripts & services online manual).
- On the Control Console, load your test service as the current service (by clicking on the service slot).
- Click through to the 'Live video' screen where you can see the animals in the arenas.
- Click on 'Run' and, once the autoreference image is taken, watch how the crosshairs track your animals.
Tips to remember:
- Your animals need to have moved around a bit during the autoreference period to provide the best reference image - you can update the value (in seconds) in the code, e.g.:
- If the crosshairs are jumping around your animal, try reducing the value of the FILTER_RADIUS and / or reduce the value of the DETECTOR_THRESHOLD.
- If the crosshair stops tracking the animals sometimes, try decreasing the DETECTOR_THRESHOLD and / or reduce the value of the FILTER_RADIUS.
- If you have an issue with the tracking of just one (or a few) animal/s, there may be a problem with the reference image (perhaps the animal/s didn't move during the autoreference period):
- Go to the Assets directory and check the autoref.bmp - the Assets directory only contains one autoref.bmp - the most recent one taken.
- Try increasing the AUTOREF_TIMEOUT period to increase the likelihood of the animal moving.
- In the reference image below you can see one animal did not move (top left well), and consequently the tracking in this arena disappeared every time the animal crossed this dark part of the arena.
Reference image (above) which shows animal in top left well because this animal did not move at all during the period in which the reference image was taken
Tracking video examples
The following videos were captured when testing SET function values for mysis shrimps in the MWP unit. We started with the standard SET values for larval zebrafish and after individually tweaking the FILTER_RADIUS and DETECTOR_THRESHOLD we found the following SET values tracked the animals best:
SET(TILE_SIZE,5) SET(DETECTOR_THRESHOLD,8) SET(SEARCH_DISTANCE,10) SET(SEARCH_STEP,3) SET(FILTER_RADIUS,6)
The tracking also worked well with a lower DETECTOR_THRESHOLD (down to a value of 3).
The tracking crosshair is jumping on the animals in this video.
The FILTER_RADIUS in this video was set at 1. All the other SET function values were as above.
> The FILTER_RADIUS needs to be increased.
If the FILTER_RADIUS is set too high, not all the animals will be tracked, as demonstrated in this video:
The FILTER_RADIUS is set at 20. All the other SET function values were as above.
> The FILTER_RADIUS needs to be less.
The tracking 'crosshair' loses the animals sometimes in this video.
The DETECTOR_THRESHOLD was set to 16, all the other SET function values were as above.
> The DETECTOR_THRESHOLD needs to be lower (set at 8 the tracking was reliable).
Reliable tracking is demonstrated in this video.
The SET function values are as detailed above.