Knowledge Base

Overview

This technical note describes how you can merge heatmaps into one when the data have been collected in different arenas or apparatuses.

Use Case Example

An EthoVision XT experiment has subjects being grouped based on the treatment level (or genetic background, etc.). Subjects are tested in four separate arenas. Because of the randomized design, each arena will be used for all treatment levels/groups. For example, Arena 1 will receive a subject of treatment level A in trial 1, then a subject of level B in trial 2 etc. As a result, one arena will not contain data of all trials with a specific group. The researcher would like to create a heatmap with all the trials that belong to that treatment level, and plot it on one arena layout, not four. EthoVision XT cannot do that with the current functionality.

Important Terms

• Reference point: A point in the 2D space defined in the EthoVision XT Arena Settings, which serves as a reference point for re-calculation of the x,y coordinates of the subjects. The reference point must be defined in all the arenas.
• JavaScript variable: A custom variable defined in the EthoVision XT Analysis profile based on JavaScript code. JavaScript variables are defined to convert the original x,y coordinates to a new set of coordinates relative to the point of reference.

What You Need

• EthoVision XT 16 or 17. If you have EthoVision XT 15, contact Noldus. You can still work with JavaScript by adding a registry key.
• Microsoft Excel.
• Power Map for Microsoft Excel, or software for creating heatmaps, for example R, MatLab, or OpenJump HORAE (featured in this note).

Assumptions

You have an experiment with two or more arenas oriented in the same direction.

Choose what applies:

• You still have to track the subjects. Go to Step 1a.
• You have already acquired the tracks. Go to Step 1b.

Step 1a - Draw the Axis Origin for Each Arena

1. Open the Arena Settings that you want to use. Draw the arenas, the zones, and do the calibration as usual.
2. Choose a point in the arenas that you want to use. For example, a corner of the cages.
3. Right-click the Calibration layer and select Unshare this Calibration.
4. On the panel at the right hand side, click one of the Arena layers (e.g. Arena 1).
5. Click the Calibration Axes button below the layers list.
6. Leave the coordinates of the origin to 0,0 and click OK.
7. Move the Axes object in such a way that the origin of the x,y axes is over the reference point.
8. Repeat steps 4 through 7 for each arena.
9. At this point, each arena should have its own Axes object positioned over the reference point and oriented the same way. You can now acquire the data. Next, go to Step 2.

Step 1b - Add a Reference Point to Each Arena

1. Open the Arena Settings that you used to acquire the data.
2. Under the layer Arena 1, click the layer named Zone Group 1 (or any other zone layer).
3. From the tool bar choose Add point.
4. Click over a specific location and give the point a name.
5. Repeat steps 2 through 4 for the remaining arenas. Choose to use the same point name (for example: SW corner).
6. Each arena should have its own reference point. Make sure that the points are listed under the corresponding arena layer.
7. Create or open an Analysis profile.
8. Under Custom Variables select JavaScript Continuous.
9. In the window that opens, delete the text already present. Copy the text under JavaScript code for x (replace "SW corner" with the name of your reference point) and paste it in the window. Next, click OK.
10. Under Custom Variables select JavaScript Continuous again. In the window that opens, delete the text. Copy the text under JavaScript code for y (replace "SW corner" with the name of your reference point) and paste it in the window. Next, click OK.
11. At this point you should have two JavaScript Continuous entries in your Data profile. Rename the variables to X and Y, respectively. To rename a variable, right-click its name and select Rename.
12. Optional: Visualize the variables in Integrated Visualization to check they are correct. The values displayed should be the coordinates x and y of each subject relative to the reference point.

Note: The new coordinates are in mm, no matter what you have selected as Measurement Units in EthoVision XT.

Go to Step 2.

JavaScript Code for x

// This code returns the x coordinate relative to a point
// Make sure you define this point in all the arenas
const g_zone = "SW corner";
function Start()
{
}
function Stop()
{
}
function Process()
{
   var pt1 = GetCenter();
   var pt2 = GetPointPoi(g_zone);
   if (pt1)
   {
      var xc = pt1.x - pt2.x;
      SetOutput(xc);
   }
   else
   {
      SetOutputMissing();
   }
}

JavaScript Code for y

// This code returns the y coordinate relative to a point
// Make sure you define this point in all the arenas
const g_zone = "SW corner";
function Start()
{
}
function Stop()
{
}
function Process()
{
   var pt1 = GetCenter();
   var pt2 = GetPointPoi(g_zone);
   if (pt1)
   {
      var yc = pt1.y - pt2.y;
      SetOutput(yc);
   }
   else
   {
      SetOutputMissing();
   }
}

Step 2 - Export the Tracks That Belong to a Specific Group or Treatment Level

1. In EthoVision XT, make a Data profile and use the Filter function to select the tracks of one group or treatment level (for example, control subjects).
2. Choose Analysis > Export > Raw Data. Choose Excel as export format.
3. Repeat steps 1 and 2 to create different datasets, one for each treatment level. For each treatment level, make a Data profile and export the data. You will create a heatmap for each dataset.

Step 3 - Prepare the Excel Files

If you are going to use Microsoft Excel 3D Maps, see the procedure for creating one global file for 3D Maps below.

Procedure for Creating One File per Subject

1. Each Excel file corresponds to one trial and contains one, two or more tabs depending on which arenas contain data for a specific group or treatment level. If you have two or more tabs, you must save them as separate Excel files (move a tab to the front and select Save As; repeat this for all the tabs).
2. Open each Excel file and delete the rows up to the headers. Also delete the row with the units, immediately above the data. The file should look like this: row 1 with the headers, row 2 onwards with the data.
3. Save each file in the format that your software for generating heatmaps requires. If you use OpenJump HORAE or R, the format CSV (MS-DOS) should work fine.

Procedure for Creating One Global File for 3D Maps

1. Open the Excel files and copy the X and Y coordinates of each of them to one global file. Append the rows instead of creating multiple columns. There should be no empty rows in between.
2. Optional: Add an extra column which specifies the subject name. You can use this column to show the heatmap in different colors based on the subject identity.
3. Save the new file. This file should contain all the X,Y coordinates of subjects in one group, in just two columns.
4. Repeat the steps above for each group or treatment level.

Step 4a - Create the Heatmap in 3D Maps

1. Open a global file for a specific group or treatment level.
2. Right-click the image of the Earth and select Change Map Type.
3. Select New Custom Map. Leave the selection as it is and tilt up the default background.
4. In the Field List, drag X and Y to the Location box and specify X Coordinate for X and Y Coordinate for Y.
5. On the Layers pane, choose Change visualization to Heat Map.
6. Click on Layer Options and adjust the settings when necessary, but keep Visual Aggregation set to Sum.

Step 4b - Create the Heatmap in OpenJump HoRAE

OpenJump HoRAE is free software for analysis and visualization of spatial behavior. You can import a global file for all subjects or separate files, one per subject. Separate files can be visualized in separate layers and contribute to a global heatmap.

Install the Software

1. Download from https://www.researchgate.net/publication/349224514_OpenJUMP_HoRAE_Software
2. Extract the files from the zip file and copy them to your PC.
3. Run the file .../bin/OpenJump.exe.

Import the CSV Files into OpenJump HoRAE

1. Choose File > Open Files.
2. Select the CSV files (Ctrl + click each file) and click Next > Finish. The tracks are imported as layers.
3. Save the Project with a name (.jmp).
4. Select all layers, right-click and choose Combine Selected Layers.
5. Save each new layer by right-clicking and selecting Save Dataset as. Save layers in the same folder as the project.
6. To make the heatmap, select the Combined layer and from the MOVEAN menu choose HRE > Point KDE > Point Kernel Density.
7. The most important setting is the Distance h (smoothing factor) which is similar to the Smoothing value in EthoVision XT. You can have the software calculate it for you or you can enter a value in the same units as the coordinates. The value Cell Size is the size of each pixel in the heatmap: the greater the value, the grainier the image.
8. To change colors, select the layer Combined-KDE and from the Raster menu choose Raster Color Editor.
9. To hide the original data points, de-select all the layers except Combined-KDE.

Extras

Create Probability Contours

1. Select the layer Combined-KDE and from the MOVEAN menu choose HR Analysis > Create Probability Contours from Raster.
2. Enter the probability value (for example, 50%) and click OK.
3. De-select the other layers to view the contours.

Source: EthoVision XT 17.5 - Technical Note - Merging heatmaps