# Commands and functions for JavaScript variables

Aim

In this topic you find the commands and functions that you can use to extract process tracking data with JavaScript code.

Get started

We assume that you have basic knowledge about JavaScript. To get started with JavaScript we recommend this online compiler:

https://repl.it/languages/javascript

Many courses on the internet concern JavaScript for web page developers. An excellent course more focused on JavaScript as a data processing tool can be found here:

https://www.youtube.com/watch?v=Bv_5Zv5c-Ts

Extract subject features

Use the functions below to extract the position and other features of your subjects.

▪GetCenter, GetNose, GetTail

▪GetSubjectCenter, GetSubjectNose, GetSubjectTail

▪GetArea, GetChangedArea

▪GetSubjectArea, GetSubjectChangedArea

▪GetElongation

▪GetSubjectElongation

▪GetViewDirection

▪GetSubjectViewDirection

Extract other data

▪GetSampleTime

▪GetPixelChange

▪GetDistanceToZone

▪GetDistanceToPoi

▪GetBehaviorEvent

▪GetCommand

▪GetSignal

▪new Point

▪GetPointPoi

Query data

Use the functions below to ask simple questions, like Is the subject in the central zone? The software gives a boolean answer (true/false).

▪IsInZone (discontinued)

▪IsSubjectCenterInZone, IsSubjectNoseInZone, IsSubjectTailInZone

▪IsPointInZone

▪Point.Equals

▪IsSubjectActor

Calculate

▪Distance

▪Point.Distance

▪TurnAngle

▪Heading

▪SetOutput

▪SetOutputMissing

GetCenter, GetNose, GetTail

Returns the x,y coordinates of the center-point, nose-point or tail-base point of the subjects in a single-subject trial, respectively. Use this function in a single-subject experiment, or in a multi-subject experiment to extract the body points of the focal subject.

▪syntax

GetCenter()

GetNose()

GetTail()

▪example 1

In the following example, the code verifies if the center point of the subject, when found, is in the zone named Zone 1.

const g_Zone = "Zone 1";

(...)

function Process()

{

var ptC = GetCenter();

if (ptC)

{

g_bInZone = IsInZone(g_Zone, ptC);

}

▪example 2

In the following example, we calculate the average x coordinate of the center point and the nose point.

var ptC = GetCenter();

var ptN = GetNose();

var x_avg = ptC.x + ptN.x;

GetSubjectCenter, GetSubjectNose, GetSubjectTail

Returns the x, y coordinates of a body point of a specific subject in a multi-subject experiment. You can use this function to compare the position of different subjects in the same JavaScript variable.

See also the sample experiment Subject Counter with JavaScript code XT160, which you can find on my.noldus.com, under Downloads > EthoVision XT > Drivers and tools.

▪syntax

GetSubjectCenter(Subject name)

GetSubjectNose(Subject name)

GetSubjectTail(Subject name)

▪arguments

Subject name: the name of one of the subjects as defined in the Experiment Settings.

▪example

In the following loop (not shown entirely), the center point of each subject is loaded in the variable pt.

const g_aSubjects = ["Subject 1", "Subject 2", "Subject 3", ... ]

(...)

for (i = 0; i < g_aSubjects.length; ++i)

{

var pt = GetSubjectCenter(g_aSubjects[i]);

(...)

Note that g_aSubject.length function gets the length of the array variable g_aSubjects which contains the names of the subjects. The variable g_aSubjects is defined at the top of the script.

GetArea, GetChangedArea

Returns the current value of the subject’s area (in practice, the yellow blob that you see during tracking), and the area that has changed from the previous sample, respectively. Use these functions for

▪The subject in a single-subject experiment.

▪The focal subject in a multi-subject experiment. Here “focal” refers to the subject for which the statistics are calculated.

Areas are expressed in internal units (mm2), independent of the units selected in the Experiment Settings. For information on the Changed area, see Rotation.

▪syntax

GetArea()

GetChangedArea()

▪example

var a = GetArea();

var ca = GetChangedArea();

▪notes

GetArea and GetChangedArea are not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ body contour.

GetSubjectArea, GetSubjectChangedArea

GetSubjectArea returns the current value of the area of a specified subject in a multi-subject experiment.

GetSubjectChangedArea returns the area of the subject in a multi-subject experiment that has changed from the previous sample. For information on the Changed area, see Rotation.

The subject’s area is the area of the yellow blob that you see during tracking. It is expressed in internal units (mm2), independent of the units selected in the Experiment Settings.

▪syntax

GetSubjectArea(“subject name”)

GetChangedArea(“subject name”)

where Subject name is the name of the subject specified in the Experiment settings.

▪example 1

var a = GetSubjectArea(“Subject 1”);

▪example 2

// This for loop extracts the area for a number of subjects

for (i = 0; i < g_aSubjects.length; ++i)

{

var AreaSubj = GetSubjectArea(g_aSubjects[i]);

...

}

▪notes

GetSubjectArea and GetSubjectChangedArea are not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ body contour.

GetElongation

GetElongation returns the current value of Body elongation for

▪The subject in a single-subject experiment.

▪The focal subject in a multi-subject experiment. Here “focal” refers to the subject for which the statistics are calculated.

It is expressed as a number between 0 and 1. To obtain the same as the dependent variable Body elongation, multiply it by 100.

▪syntax

GetElongation()

▪example

var y = GetElongation();

if (y != null)

{

SetOutput(y*100);

}

else

{

SetOutputMissing();

}

▪notes

GetElongation is not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ body contour.

GetSubjectElongation

Returns the current value of Body elongation for a specified subject in a multi-subject experiment. It is expressed as a number between 0 and 1. To obtain the same as the dependent variable Body elongation, multiply it by 100.

▪syntax

GetSubjectElongation(“Subject name”)

where Subject name is the name of the subject specified in the Experiment settings.

▪example

// This for loop extracts the body elongation for a number of subjects

for (i = 0; i < g_aSubjects.length; ++i)

{

var EloSubj = GetSubjectElongation(g_aSubjects[i]);

...

}

▪notes

GetSubjectElongation is not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ body contour.

GetViewDirection

Returns the current value of the Head direction variable for

▪The subject in a single-subject experiment.

▪The focal subject in a multi-subject experiment. Here “focal” refers to the subject for which the statistics are calculated.

It is expressed in radians. Note that the Head direction dependent variable provided by EthoVision XT is expressed in degrees. To convert your JavaScript variable to degrees, see the example below.

▪syntax

GetViewDirection()

▪example

var dir = GetViewDirection();

If you want to extract the head direction in degrees, convert the value of head direction to degrees with the following formula:

function toDegrees(angle)

{

return angle * (180 / Math.PI);

}

(...)

var dir = GetViewDirection();

angle = toDegrees(dir);

▪notes

GetViewDirection is not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ head direction.

GetSubjectViewDirection

Returns the value of the Head direction of a specified subject in a multi-subject experiment, for the current sample. The value is given in radians. Note that the Head direction dependent variable provided by EthoVision XT is expressed in degrees. To convert your JavaScript variable to degrees, see the example in GetViewDirection.

▪syntax

GetSubjectViewDirection(“subject name”)

where Subject name is the name of the subject specified in the Experiment settings.

▪example

// This for loop extracts the Head direction in radians for a number of subjects

for (i = 0; i < g_aSubjects.length; ++i)

{

var HDirSubj = GetSubjectViewDirection(g_aSubjects[i]);

...

}

▪notes

GetSubjectViewDirection is not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ head direction.

GetSampleTime

Returns the sample time (in seconds) of the sample currently processed. You can use this function to calculate the latency of an event that you cannot obtain through the other dependent variables.

note The sample time in this function is the track time, that is, the time elapsed from the start of the track (the first sample), not the start of the trial.

▪syntax

GetSampleTime()

▪example

The following example outputs the value of the current sample time. If it is not found, a missing value is assigned with the SetOutputMissing command (see below).

function Process()

{

var st = GetSampleTime();

if (st!= null)

{

SetOutput(st);

}

else

{

SetOutputMissing();

}

GetPixelChange

Returns the current proportion of pixels in the arena that have changed intensity above the specified Activity threshold from the previous video frame. This proportion can be between 0 (no pixel in the arena has changed intensity value above the threshold) and 1 (all pixels in the arena have changed intensity value above the threshold). A pixel change value of 0.156 (expressed as proportion) corresponds to an Body angle value without smoothing of 15.6%.

To use this variable, you must select Activity analysis in the Experiment Settings and define the threshold value in Activity settings in the Detection settings. For information on the pixel change, see Body angle.

▪syntax

GetPixelChange()

▪example

var a = GetPixelChange();

GetDistanceToZone

Returns the distance of a (body) point from a zone. The distance is zero if the body point is within the zone. Distances are expressed in internal units (mm), independent of the units selected in the Experiment Settings.

▪syntax

GetDistanceToZone(Zone, Point)

▪arguments

Zone: the name of the zone as it appears in the Arena Settings; e.g. “Platform”.

Point: the name of the point; usually a body point.

▪example

const g_strZone = "Object";

(...)

function Process()

{

var ptNose = GetNose();

var dist = GetDistanceToZone(g_strZone, ptNose);

GetDistanceToPoi

This is similar to GetDistanceToZone; it returns the distance from the specified point of interest. Distances are expressed in internal units (mm), independent of the units selected in the Experiment Settings.

▪syntax

GetDistanceToPoi(Point of interest, Point)

▪arguments

Point of interest: the name of the point of interest as it is defined in the Arena Settings.

Point: the name of the point to which distance is determined; usually a body point.

GetBehaviorEvent

This command returns the value of an event scored manually using the Manual Scoring function. If you work with Live Mouse Tracker, this command also works with the events listed under Raw Live Mouse Tracker data in the Analysis profile.

▪syntax

GetBehaviorEvent(behavior)

GetBehaviorEvent(behavior, receiver)

▪arguments

Behavior: The name of the behavior as in the Manual Scoring Settings or listed under Raw Live Mouse Tracker data in the Analysis profile.

Receiver (optional): The name of the receiver, in case of multi-subject tracking.

▪return values

undefined: no behavior event

1: start of a state event

2: stop

4: point event

▪example

The following code gets the values of the behavior Sleep that was scored. The function UpdateState at the top copies the values of Sleep, 1 or 2 to a new state variable g_bState with values true or false, respectively.

var g_bState = false;

function UpdateState(evt)

{

if (evt != undefined)

{

if (evt == 1)

{

g_bState = true;

}

else if (evt == 2)

{

g_bState = false;

}

}

}

function Process()

{

var evt = GetBehaviorEvent("Sleep");

UpdateState(evt);

SetOutput(g_bState);

}

GetCommand

Returns the event that represent a command to a hardware device.

▪syntax

GetCommand(Device name, Command name)

▪arguments

Device name: the name of the device specified in EthoVision XT. For example, “Device A”. To know the device name, in the Arena Settings click the Arena-Hardware Mapping button, under Device name click the cell of the device you require and press Ctrl+C. Paste the text into the JavaScript code as Device name.

Command name: the name of the command used in the Trial Control Settings. For example, “Drop pellet”. To know the command name, open the Trial Control Settings, locate the Action box that contains that command and click Settings. Take note of the text near Action to perform. Enter this text in the JS code as Command name.

▪example

In the following example, JavaScript reads the command “Drop pellet” of a Pellet dispenser with name Device A and outputs the value for each sample of the track (1 = drop a pellet; missing value = no pellets dropped).

function Process()

{

var DropPellet = GetCommand("Device A", "Drop pellet");

SetOutput(DropPellet);

}

GetSignal

Returns the value of a hardware signal.

▪syntax

GetSignal(Device name, Signal name)

▪arguments

Device name: the name of the device specified in EthoVision XT. For example, “Device B”. To know the device name, in the Arena Settings click the Arena-Hardware Mapping button, under Device name click the cell of the device you require and press Ctrl+C. Paste the text into the JavaScript code as Device name.

Signal name: the name of the signal that you want to acquire. For example, “Number of licks”. To know the signal name, open an Analysis profile, click the button next to Hardware continuous, select a Device type, Device, and Signal. Take note of the text near Signal, and enter this text in the JS code as Signal name.

▪example

In the following example, JavaScript reads the value of the signal “Number of licks” of a lickometer (Device B) and outputs it for each sample of the track.

function Process()

{

var s = GetSignal("Device B", "Number of licks");

SetOutput(s);

}

new Point

With the new Point statement you can define a point in space.

▪syntax

new Point(x,y,z)

▪arguments

x, y, z (z is optional): The coordinates in mm based on the calibration axes and origin in the Arena Settings.

▪example

pt1 = new Point(200, 300);

▪note

You cannot visualize the position of points defined with JavaScript. To do so, define points in the Arena Settings.

GetPointPoi

With this command you can extract the coordinates of a point of interest of the center of a zone or arena. Note that GetPointPoi returns the position of the point, then you have to extract the coordinates with additional commands (e.g. x = pt.x).

▪syntax

GetPointPoi(point)

▪arguments

point: The name of the point or the zone or arena, of which you want to find the center.

▪example

const g_zone = "Zone 1";

function Start()

{

}

function Stop()

{

}

function Process()

var pt = GetPointPoi(g_zone);

var xc = pt.x;

var xy = pt.y;

IsInZone

This function has been replaced by other functions in EthoVision XT 19 (see below).

▪For single-subject tracking: see IsPointInZone

▪For multi-subject tracking: see IsSubjectCenterInZone, IsSubjectNoseInZone, IsSubjectTailInZone.

You can still use IsInZone in your code, but it won’t work properly when analyzing data points in hidden zones.

IsSubjectCenterInZone, IsSubjectNoseInZone, IsSubjectTailInZone

Use this function to determine if a body point of a subject is within a zone. The zone must be defined in the Arena Settings. The return value is boolean (true or false).

▪syntax

IsSubjectCenterInZone(Subject name, Zone name);

IsSubjectNoseInZone(Subject name, Zone name);

IsSubjectTailInZone(Subject name, Zone name);

▪arguments

Subject name: the name of one of the subjects listed in the Experiment Settings.

Zone name: the name of the zone of interest defined in the Arena Settings; for example, "Zone 1". You can specify the name directly (“Zone 1” with quotes), or a variable that contains that name. The zone can be a single zone, a cumulative zone, an entry zone, or a hidden zone.

▪example - one subject

var bC = IsSubjectCenterInZone(“Subject 1”, “Zone 1”);

var bN = IsSubjectNoseInZone(“Subject 1”, “Zone 1”);

var bT = IsSubjectTailInZone(“Subject 1”, “Zone 1”);

or

const g_sZone = "Zone 1"

var bC = IsSubjectCenterInZone(“Subject 1”, g_sZone);

var bN = IsSubjectNoseInZone(“Subject 1”, g_sZone);

var bT = IsSubjectTailInZone(“Subject 1”, g_sZone);

▪example - multiple subjects

var bC1 = IsSubjectCenterInZone(“Subject 1”, “Zone 1”);

var bC2 = IsSubjectCenterInZone(“Subject 2”, “Zone 1”);

IsPointInZone

Use this function to determine if a point (a body point, or a point of interest) is within a zone. The zone must be defined in the Arena Settings. The return value is boolean (true or false).

▪syntax

IsPointInZone(Zone name, Point name)

▪arguments

Zone name: the name of a zone defined in the Arena Settings; for example, "Zone 1".

Point name: The name of a body point or a point of interest defined in the Arena Settings.

▪example

pt = GetCenter();

var b1 = IsPointInZone(“Zone 1”, pt);

or

pt = new Point (10, 10);

var b1 = IsPointInZone (“Zone 1”, pt);

Point.Equals

Checks if two points are equal.

▪syntax

point1.Equals(point2).

▪arguments

point 1: the first point

point 2: the second point

▪example

The variable b gets the value 1 if the two points pt1 (the center of the subject) and pt2 (a point in space defined with the new statement) have the same coordinates.

var pt1 = GetCenter();

var pt2 = new Point(1.0, 2.0);

var b = pt1.Equals(pt2);

▪errors

If one of the two points is null, the value is not calculated and an invalid reference is returned.

IsSubjectActor

Determines if the subject specified (argument) is currently the actor (focal subject) of the track being analyzed. The return value is boolean (true or false). You can use this function to skip comparisons and calculations that do not make sense.

▪syntax

IsSubjectActor(Subject name)

Where Subject name is the name of one of the subjects listed in the Experiment Settings.

▪example

In this example a for loop scans the list of i subjects Subject 1, Subject 2, etc. contained in the array g_aSubjects[i] and calculates the distance between the focal subject (that is, the subject of the currently analyzed track) and the subject i.

for (i = 0; i < g_aSubjects.length; ++i)

var ptSubj = GetSubjectCenter(g_aSubjects[i]);

(...)

//invoke Distance function

var Dist = Distance(ptFocal, ptSubj);

Obviously at some point in this loop the focal subject and the subject i are the same individual. You can exclude the distance calculation focal-to-focal by inserting an extra check.

var b = IsSubjectActor(g_aSubject[i]);

if b = true

{

//invoke distance function

Distance

To calculate the distance between two points, see Point.Distance. You can also use the code here below and invoke the function in your script. Distance is expressed in internal units (mm), independent of the units selected in the Experiment Settings.

▪function

// Function to calculate distance between two points

function Distance(pt1, pt2)

{

var dx = pt1.x - pt2.x;

var dy = pt1.y - pt2.y;

return Math.sqrt(dx * dx + dy * dy);

}

▪example of function call

//Get the center point of subject 1 and subject 2

var cSubj1 = GetSubjectCenter(“Subject 1”);

var cSubj2 = GetSubjectCenter(“Subject 2”);

//call distance function

var Dist = Distance(cSubj1, cSubj2);

▪errors

If one of the two points is null, the value is not calculated.

Point.Distance

Calculates the distance between two points. Distance is expressed in internal units (mm), independent of the units selected in the Experiment Settings.

▪syntax

point1.Distance(point2)

▪arguments

point1: the first point

point2: the second point

▪example

var pt1 = GetCenter();

var pt2 = GetNose();

var dist = pt1.Distance(pt2);

▪errors

If one of the two points is null, the value is not calculated and an invalid reference is returned.

TurnAngle

Returns the angle in radians between three points. The name suggests that this function is restricted to turn angles but you can use it to calculate any angle formed by three points in general. See also Turn angle

▪syntax

TurnAngle(Point 1, Point 2, Point 3)

▪arguments

Point 1: the name of the begin point.

Point 2: the name of the middle point.

Point 3: the name of the end point. This is the point at the current sample time, while Point 1 and Point 2 are the points at two immediately preceding sample times.

▪example

ta = TurnAngle(g_aPoints[0], g_aPoints[1], g_aPoints[2]);

where g_aPoints is an array variable of length 3.

Remember that TurnAngle is in radians. At the top of the code, define a function to obtain the value in degrees:

function toDegrees(angle)

{

return angle * (180 / Math.PI);

}

(...)

var tadg = toDegrees(ta);

▪errors

If any of the three points is null, the value is not calculated.

Heading

Returns the value of heading in radians based on two sample points. See Heading

▪syntax

Heading(Point 1, Point 2)

▪arguments

Point 1: Begin point.

Point 2: End point.

To calculate heading, Point 1 is the point at the previous sample time and Point 2 the point at the current sample time.

▪example

var hd = Heading(g_aPoints[0], g_aPoints[1]);

where g_aPoints is an array variable of length 2.

At the top of the code, define a function to obtain the value in degrees:

function toDegrees(angle)

{

return angle * (180 / Math.PI);

}

(...)

var hdg = toDegrees(hd);

▪errors

If one of the two points is null, the value is not calculated.

SetOutput

Assigns a value to the JavaScript variable for the current sample time.

▪syntax

SetOutput(Value)

SetOutput(Output, Value)

▪arguments

Value: the value that you want to assign to the variable at the current sample time.

▪For JavaScript Continuous variables: a rational number.

▪For JavaScript State variables: true or false.

▪For JavaScript Event variables: 0 or 1.

Output: Output number. When the variable has just one value per sample, like in most applications, then you do not need to specify Output. When the variable has multiple outputs, like in a state variable with 4 possible states, specify the output in each line (beginning from zero). For example

SetOutput(0, bOutput1); //write first state

SetOutput(1, bOutput2); //write second state

SetOutput(2, bOutput3); //write third state

SetOutput(3, bOutput4); //write fourth state

▪example

if (x != null)

{

SetOutput(x);

}

▪errors

If the value is null or undefined, the output will be missing.

▪notes

When the variable has multiple outputs, remember to specify the Number of outputs at the bottom of the JavaScript window.

SetOutputMissing

Assigns a missing value to the JavaScript variable for the current sample time.

▪syntax

SetOutputMissing()

▪example

In the following example, if the value of x is not null, it is assigned to the output of the JavaScript variable; otherwise it is set to missing.

if (x != null)

{

SetOutput(x);

}

else

{

SetOutputMissing();

}

See also

▪JavaScript continuous

▪JavaScript state

▪JavaScript event