Wintrack

Matrix statement

 Matrix
   Data=PosX|PosY|Stamp|Date|Dtim|Path|Time|Speed
     |DirAbs|DirAir|DirDev|DirRel|DirPol|LoopSpin|Linearity|Pred
     |DistCtr|DistRad|DistBder|DistCorn|DistLin
     |FiltCrit|Field|Event|SupData|Compare
   [Field1=field_name|event_key|data_channel]
   [Field2=field_name]
   [Smooth=smoothing_frame]
   [MinSpeed=minimal_speed]
   [MaxAng=maximal_angle]
   [MinDur=minimal_duration]

Type conventions and statement syntax are explained in the Glossary.

Clears the active data matrix, calculates a new parameter and fills the data matrix cells with the new results. Each cell in the data matrix represents one data point, each column of the matrix one trial of the case document being analyzed.

Parameters...

Data
Radio button parameter indicating which parameter has to be calculated. There is no default, one of the following options must be specified:

PosX = x-coordinate of the current data point.

Posy = y-coordinate of the current data point.

Stamp = time stamp of the current data point in s elapsed since begin of trial.

Date = GMT calendar time of current data point in s elapsed since 1.1.1970 00:00:00.

Dtim = time of day of current data point in s elapsed since 00:00:00 GMT of current day.

Path = length of the path segment connecting the nearest upstream point to the current data point.

Time = time stamp difference between the current data point and the nearest upstream point.

Speed = local speed at the current data point defined as the ratio Path/Time. The matrix cells representing the first point of the trials are left empty, that is contain a missing value code.

DirAbs = absolute direction of the path segment connecting the nearest upstream point to the current data point with 0° being East, 90° North, and -90° South.

DirAir = absolute direction of the air line connecting the begin of the path to the current data point with 0° being East, 90° North, and -90° South.

DirDev = deviation of a straight line connecting the begin of the path to the current data point from the airline between the begin of the path and the center of Field1. Positive values indicate counter-clockwise deviations. The matrix cells representing the first point of the trials are left empty, that is contain a missing value code.

DirRel = deviation of the path segment connecting the nearest upstream point to the current data point from a straight line connecting the current data point to the center of Field1. Positive values indicate counterclockwise deviations. The matrix cells representing the first point of the trials are left empty, that is contain a missing value code.

DirPol = deviation of a straight line connecting the arena center to the current data point from a second line connecting the arena center to the center of Field1. Positive values indicate counterclockwise deviations. The matrix cells that represent points falling on the arena center are left empty, that is contain a missing value code.

LoopSpin = difference between DirAbs values of the current and nearest downstream point. The values are filtered according to the values specified for MinSpeed, MaxAng, and MinDur. They are the smoothed using the frame given in Smooth. The matrix cells representing the first two points of the trials are left empty, that is contain a missing value code.

Linearity = ratio airline / traveled distance between beginning and end of a time window framing the current data point. Duration of the window in s is specified using Smooth.

Pred = path predictability by linear interpolation within a sliding window whose duration in s is specified using Smooth. Result is between 0 (completely unpredictable) and 1 (constant speed along a straight trajectory).

DistCtr = distance between the current point and the center of Field1

DistBder = distance of the current point to the border of Field1. Result is positive if the current point is inside the field and negative if it is outside the field.

DistCorn = distance of the current point to the nearest corner of the bounding rectangle of Field1.

DistRad = radial distance of the current point from a circle drawn through Field1 and around the arena center. Result is positive if the current point is outside the circle and negative if it is inside.

DistLin = shortest distance between the current data point and the straight line connecting the center of Field1 to the center of Field2. Result is positive of the current point lies to the left of the line.

FiltCrit = distance between the current data point and a point modeled for the same time stamp using the nearest up- and downstream data points. Results may be used to fine tune threshold for data filtering.

Field = number of the field in which the animal is currently staying. Numbers are indices into a contiguous range of fields defined by the Field1 and Field2 parameters. The first field in the range is referred to as 0. If the animal is staying in the intersection area of two or more fields, it is assumed to be in the field with the lowest range number. If the animal is not staying inside a field of the range, the data point is assigned a missing value code. This option requires also the Smooth and MinDur parameters to be specified!

Event = current value of the event data channel. If one of the allowed 16 event key names is specified for Field1, the current state of that key is retrieved: 0=up, 1=pressed.

SupData = current value of the supplementary data channel specified by the Field1 parameter.

Compare = after comparing paths using one or several Compare statements, use the current path comparison results to build a the matrix.

Field1
Name parameter whose meaning depends on the value specified for the Data parameter:

If Data=DirDev, DirRel, DistCtr, DistBder, or DistLin it specifies the name of a field defined in the currently loaded setup and serving as reference for the calculations.

If Data=Field, this parameter indicates the name of the first field in a contiguous range of up to 512 fields in the currently loaded setup.

If Data=Event this parameter is used to specify the name of the event key whose state is to be retrieved. Valid names are: F1-F12, Space, Shift, Control, Alt.

If Data=SupData this parameter specifies the number of the supplementary data channel from which values are to be retrieved.

Field2
Name parameter indicating the name of a field defined in the currently loaded setup. Must be specified if DistLin or Field has been specified for Data. If Data=Field, this parameter indicates the name of the last field in a contiguous range of up to 512 fields in the currently loaded setup.

Smooth
Number parameter which must be specified if Loopspin, Linearity or Field has been specified for Data. For Data=LoopSpin, it indicates a time window for running average smoothing of the obtained values. Specify 0 if you do not want the data to be smoothed. Note that smoothing does not affect filtering according to the values specified for MaxAng and MinSpeed. Filtering according to the values specified for MinDur, by contrast, is carried out after the smoothing process. For Data=Linearity, this parameter specifies the maximal time difference between begin and end of the path segment used to calculate the linearity index. For Data=Field, this parameter indicates how long the animal must have left a field for a reentry into the same field to be registered as a separate entry.

MinSpeed
Number parameter indicating a speed threshold to be applied if LoopSpin has been specified for Data. Cells will be cleared, that is filled with a missing value code, if the corresponding or nearest downstream data point has a Speed value smaller than than the specified threshold. This operation is not affected by the Smooth parameter.

MaxAng
Number parameter indicating a threshold to be applied if LoopSpin has been specified for Data. All cells that contain values greater than the specified threshold will be cleared, that is filled with a missing value code. This operation is not affected by the Smooth parameter.

MinDur
Number parameter which must be specified if Loopspin or Field has been specified for Data. For Data=LoopSpin, it indicates a curve duration threshold to be applied after smoothing of direction changes has occurred. The path is divided into curves, that is segments in which the sign of direction change remains constant, either clockwise or counterclockwise. All cells that are part of a curve with a duration less than the specified threshold will be filled with a missing value code. For Data=Field, this parameter indicates how long the animal must stay in a field for it to be registered as a field entry.

Note that...

You must execute at least one Matrix and statement before you can execute any of the other variable definition file statements. Wintrack maintains a single data matrix which will be overwritten each time you use the Matrix statement.

Additional information...

Managing custom variable definition files provides general information on the management of custom variable definition files.
The Flowchart of advanced data analysis gives a synopsis of data and variable types.
There is a topic describing how to build a custom variable definition file.
There is a list of all available variable definition statements.
Using the Memory statement you can build collections of data matrices and selection masks for later reuse in other variables.
See Analyze Case Document command for basic information on that command.
Inside case documents provides advanced information on case documents.