MouseTracker Help

Jon Freeman
New York University
http://www.jonbfreeman.com


>>

Start

>> Running experiments

>> Creating  experiments

>> Interfacing with an external environment
 
>> About MouseTracker data

>> Analyzing data

 Step 1: Load
 Step 2: Import
 Step 3: Visualize
 Step 4: Compute
 Step 5: Export


>> Exporting data

>> Converting from MouseTracker 1.x

   
 
 

 
Analyzing data

Open Analyzer. Here is a typical procedure for analyzing data:


Step 1: Load MT files

Click the Load File button to load one individual participant’s data from an MT file, or the Load Folder button to load multiple participants’ data (all MT files from a specified folder). Once loaded, the file(s) should appear in the list on the left. It will prompt you: “Load LOG files (if any)?” LOG files are optional files tied to MT files that contain information about which trajectories in a participant’s data should be manually excluded from analysis or should be recoded. These LOG files are generated using the Exclude and Save buttons (detailed later). Hit Yes here if you would like to load LOG files (if they exist). This will exclude trajectories that have been previously excluded and saved. Hit No if you would not like to load LOG files (and thus, previous exclusions that were saved will not be loaded).

In the file list are checkboxes. Files that are checked will be used for analysis, and files that are unchecked will not be used for analysis. By default, all files in a folder are checked for use. To include or exclude a file for analysis, simply check/uncheck it.

 


Step 2: Import mouse trajectories

To import mouse trajectories from these data files, click the Import button. A screen will appear. There are four tabs involved in the the Import process. At the bottom of the screen are the Load and Save buttons. You can save and load the import settings using these buttons, which creates and loads .MTS (MouseTracker settings) files.

Conditions tab

Before the Import screen appears, the program first searches through all the loaded MT files for all condition codes that were used (as specified in their experiment .CSV file) and displays them under the All used codes list. Here, you need to define which condition codes are included in Condition 1 and Condition 2 for MouseTracker to analyze. To add a code into Condition 1 or 2, simply click on the corresponding arrow pointing right. To remove a code from the Condition 1 or 2 lists, simply click the corresponding arrow pointing left. You can rename the conditions by typing in new text into the Condition 1 and Condition 2 text boxes (in this example, I kept the original “Condition 1” and “Condition 2” text, as seen in image on the left). When finished, press Go.

Analyzing manually recoded trajectories
In some cases, you may have previously analyzed your data in Analyzer and manually recoded some trajectories into a specific condition number (e.g., condition 501, rather than 1 or 2). This recoding is available only if you loaded .LOG files (see Step 1). Here, you might want to analyze trajectories recoded into a unique condition number. For instance, you may manually recoded some trajectories into unique condition number 500 and some other trajectories into unique condition number 501. You might want to analyze these side-by-side by slotting them into main conditions 1 and 2. If you right click on the All used codes list, a popup menu will appear and you will be to select Add unique condition number. You will then be prompted for the number. It will add the condition number to the list, and you can then put it into Condition 1 or 2. For instance, if you added the unique condition number 500 and put it into the Condition 1 list, any trajectories recoded as 500 in the .LOG files would be sent into Condition 1 for analysis.

Option: Correct/incorrect analysis
There is also another optional check box at the bottom to perform a Correct/incorrect analysis. If you choose to perform a correct/incorrect analysis, condition codes are defined only for Condition 1. This is because trials involving a correct are imported into Condition 1 and trials involving an incorrect response imported into Condition 2. Rather than examine two separate sets of condition codes, a correct/incorrect analysis allows you to examine one single set of condition codes, but separate out whether responses were correct versus incorrect. This is most helpful in experiments in which there are no true incorrect responses and participants are given no feedback on errors. Because correct alternatives are always specified in the experiment .CSV file, you could use this feature to separate out trials based on whether the participant responded in a way that the researcher expected (i.e., correct) versus did not expect (i.e., incorrect). For instance, imagine an experiment where participants are asked to decide whether they “like” or “do not like” different foods. There are no correct or incorrect responses here. However, when a chocolate cake is presented, we can expect that participants should respond “like,” and we may be interested to look at trials in which they respond unexpectedly (“do not like”). When participants are deciding whether they like versus do not like chocolate cake, and they ultimate decide “do not like,” you might be interested to know whether trajectories nevertheless show an attraction to the “like” alternative before settling into “do not like.” A correct/incorrect analysis would allow Condition 1 to comprise the “like” trials and Condition 2 to comprise the “do not like” trials. Thus, rather than examine two separate conditions, a correct/incorrect analysis allows a user to examine the same condition but separate out correct/expected responses versus incorrect/unexpected ones.

Option: Between subjects analysis
There an another optional check box at the bottom to perform a Between subjects analysis. If you select this, conditions codes are defined only for Condition 1. This is because trials corresponding with these codes will be loaded into Condition 1 if from one particular group of subjects and loaded into Condition 2 if from another particular group of subjects. After checking this and hitting “Go”, a window will pop up asking you to select the two groups of subjects. Note that although MouseTracker can visualize mean trajectories in a between subjects analysis, it can only compute trial-by-trial information (and does not compute mean trajectory information). This can be done manually using the output .CSV file from a between subjects analysis.
 

Restrictions tab

If you want to exclude incorrect responses from analysis, check the Exclude incorrect responses checkbox. If you want to restrict analysis to only trials whose response times are within a certain range or within a min/max cutoff, check the Restrict response times checkbox and define the Min and Max response time values. If you want to restrict analysis to only trials whose initiation times are within a certain range or within a minimum/maximum cutoff, check the Restrict initiation times checkbox and define the Min and Max initiation time values.

Time tab

Here you choose whether to conduct a Normalized time analysis or a Raw time analysis. If doing a Normalized time analysis, you set how to many time steps to time-normalize the trajectories into (default = 101). In a raw time analysis, you set the raw time (ms) cutoff and how many equal-sized raw time bins to create leading up to that cutoff. See the About MouseTracker Data sections on Time Normalization and Raw Time Analysis for more information on what these entail. A Normalized time analysis will calculate MD, AUC, x-flips, and y-flips, but not velocity, acceleration, and angle profile. In a raw time analysis, velocity, acceleration, and angle information is available, but not MD, AUC, x-flips, and y-flips.

Responses and Remapping tab

Here is where you decide which kind of responses you want to include/exclude and also set up any remapping. It shows you a visualization of the response buttons and "Start" button, much like how is done in Designer. Each response button has a checkbox. By default, all responses are checked. If a response is unchecked, any trials where that response was selected will be excluded from this analysis.

You set up remapping(s) one response button at a time. You set different response mapping(s) depending on what response is eventually clicked on, in addition to what is listed for a trial's default-compare response (see Creating experiments | Stimuli and response list for more information on default-compare). Once all remappings are set up, MouseTracker will perform each one, one at a time, in order. Remappings work by performing one or many of the following:

  • Horizontal flip (invert along the x-axis, about the Start button)

  • Vertical flip (invert along the y-axis, about the Start button)

  • Rotate 90° clockwise

  • Rotate 90° counter-clockwise

Note that remapping procedures are always performed using the center point of the Start button and the center points of the response buttons. Also note that, for horizontal and vertical flips (but not necessarily for rotations), you need to make sure that the responses you want to remap are equidistant to the "Start" button. This can be done in Designer when making an experiment .CSV file.
 

Example 1: A simple 2-choice design

In a standard 2-choice design, such as that depicted in the screenshot above, remapping is straightforward. To directly compare the two conditions, we might want to remap all trajectories that head to response #1 (on the left) over to response #2 (on the right). To begin, first click the Add Remap button. A message will appear saying "Click the source response." Then, click on response #1. It will turn green. (Or, rather than hitting the Add Remap button, you could simply double-click on the source response to begin the process).

A message will now appear saying "Click the default-compare response." Then, click on the response listed as default-compare (in the experiment .CSV file) for the particular trials you're interested in remapping. In a standard 2-choice design, this will always be the opposite/incorrect response (response #2). Click response #2 and it will turn pink. A message will now appear saying "Click the destination response." Then, click on the response location where you'd like to remap trajectories to, which in this case is response #2. Response #2 will now appear green, indicating that trajectories will be moved to this response.

         

A message will now appear saying "Click another destination or 'End Remap' to set." If there were more than 2 response alternatives, you might also want to do another remapping. For instance, after horizontally inverting the trajectories from response #1 to response #2, you might then want to rotate them into a third response location. Because we do not need do that here, we are done with this remapping and may press End Remap. (Or, you could have simply double-clicked on response #2 when selecting it as the destination to end the remapping).

A remapping has now been added to the list on the left side (see image below). It says "Resp: 1" to indicate that it will be remapping trajectories whose response was #1 (the source). It says "DC: 2" to indicate that it will be remapping only  trajectories that headed to response #1 and whose default-compare (DC) response (listed in experiment .CSV file) was #2. Again, because this is a simple 2-choice design, all trajectories that head  to response #1 will always have their default-compare response as the opposite/incorrect response (#2). Finally, it says "--> 2" to indicate that trajectories will be remapped into response #2 (the last destination). Under this information is a list in order of all remapping procedures. Here, there was only one: a horizontal flip.

To continue, you would press Go! Or, you could save all the settings and remappings into an .MTS file (so you may re-load it easily later), using the Save button.
 

Example 2: A more complicated 4-choice design

The above screenshot shows a relatively complex 4-choice design. Let's pretend that responses #4 and #2 (encompassing the horizontal axis) are correct/incorrect targets, and responses #1 and #3 (encompassing the vertical axis) are distractors. Thus, on some trials, we might expect the mouse to click on #2, but show some attraction to #3, and on other trials, to click on #2 and show attraction to #1 (depending on what stimuli were presented on the trial). We might want to take all trials in the entire experiment and remap them such that they all head vertically to response #1 and be rotated/flipped correctly such that the hypothetical distractor be located at response #2. Thus, in the example above, regardless of whether we predicted response #1 or #3 to attract participants' mouse movements en route to clicking on response #2 on a given trial, trajectories for all trials would be remapped such that they head to response #1 with the hypothetical distractor located at response #2 (regardless of whether it was #1 vs. #3 for any given trial).

To begin, first click the Add Remap button. A message will appear saying "Click the source response." Then, click on one of the response buttons. It will turn green. A message will appear saying "Click the default-compare response." Then, click on the response listed as default-compare (in the experiment .CSV file) for the particular trials you're interested in remapping. It will turn pink. As seen below, response #2 is designated as the source and response #4 as the default-compare response for this remapping. Thus, this remapping will apply to any trajectories that eventually clicked on response #2 and were hypothetically distracted by response #4 (specifically, had "4" listed under the default-compare column in the experiment .CSV file).

A message will now appear saying "Click another destination or 'End Remap' to set." Click, response #3 to first remap the trajectories from response #2 to #3 (a 90° clockwise rotation). Now, response #3 will appear in green, meaning that trajectories will now be remapped to that location. Because we want trajectories to head toward response #1, with the hypothetical distractor located at response #2, we have more remappings to do.

         

Now click on response #4, which will turn green. We have now rotated trajectories 90° clockwise again. Finally, click on response #1, which will turn green (see below). This conducts yet a third  90° clockwise rotation. Trajectories will now be remapped to response #1. Because we rotated trajectories clockwise and the default-compare response was originally located at response #3, the default-compare response is now located at response #2. To finalize the remapping, hit the End Remap button (or simply double-click response #1 when selecting it as a destination).

         

Notice that a remapping has appeared in the list on the left (see image below). It indicates that trajectories which originally headed to response #2 and whose default-compare response was #3 will now be remapped to response #1, and it will do this by performing three 90° clockwise rotations.

Now you would repeat this procedure for every relevant source response and corresponding default-compare conditions so that every single trajectory in the experiment is remapped to response #1, with the default-compare response located at response #2. For a complicated design such as this, you would likely want to use the Save button to save the remappings once finished. When done, press Go!

The sample data below in the screenshot of the main Analyzer window is from Example 1 (the simpler 2-choice design).


Step 3: Visualizing, exploring, and excluding trajectories

You can choose to visualize trajectories with their coordinates marked or not marked—to visualize with marked coordinates, check the Mark points checkbox. Hit the Visualize button. All trajectories corresponding with Condition 1 will be displayed in the left pane, appearing here as purple trajectories. All trajectories corresponding with Condition 2 will be displayed in the right pane, appearing here as blue trajectories (see image below). These colors can be changed using the Settings button. Mean trajectories aggregated across all trials (and all participants if multiple participants are included in the analysis) are displayed in the bottom left pane.

Time-courses of the mean x-position and mean y-position (across every time-step) appear in the bottom middle of the screen. To view the actual mean x-coordinate and y-coordinate data over time, simply click on the small 'Data' button over the time-course panels or click on the mean trajectory or time-course panels. A small window will appear with the data.


 


Every trajectory displayed in the Condition 1 and Condition 2 panes is able to be individually selected for more detailed information or to exclude from analysis. To select one or multiple trajectories, hover over the Condition 1 or Condition 2 pane. Notice that the mouse cursor turns into a crosshair. Hold down the mouse and drag, and notice the black rectangular selection window (as shown above). Once the mouse is released, any trajectories captured within this selection window are listed in the Selected tracks list box in the bottom right of the screen. To select a trajectory, click on the item in the list; the trajectory will be redrawn in a new color (here, black). The color of selected trajectories and the selection window can be changed using the Settings button. To obtain more detailed information about the trajectory, double-click on the trajectory item in the list and a new window will appear with details (see image on right).

You can also right click on items in the Selected tracks list, which will give you a series of options. By right-clicking, you can get detailed information on the trajectory, you can exclude a single trajectory or multiple trajectories, and you can also manually recode a single trajectory or multiple trajectories into a unique condition number (e.g., 500 or 501). This manual recoding will make trajectories disappear from the current analysis (since the analysis compares condition 1 and 2). However, the trajectories will be identified with their unique condition number and all their information will be given in the output .CSV file. If you hit the Save button, the manual recoding will be saved into the LOG file(s). Once saved in the LOG file(s), you can load the data again and go to the Import screen. You could then import trajectories from a unique manual condition code (e.g., 500 or 501) into the main Condition 1 and 2 so you can focus your analysis on these manually recoded trajectories (see Step 2 for more information on this).
 

Note that the MD, AUC, x-flip, and y-flip values are only computed after hitting the Compute button (detailed in Step 4). At this stage, they would read: “<Hit Compute>”. When first loading, it will display a time-course of the x-coordinates of the trajectory. To display a time-course of the y-coordinates, click the Y button in the bottom left of the plot. Also when first loading, it loads all the response alternatives information into the dropdown list under Alternatives. It automatically starts with the response alternative specified in that trial's default-compare column (from the experiment .CSV file). This is the default comparison unselected response. The MD and AUC values in reference to this response alternative for this trial are the ones that get aggregated into MouseTracker's average of MD and AUC in the two conditions.

To exclude the selected trajectory item(s) from analysis, hit the Exclude button. This will re-code the trajectory item(s) into condition 888 (rather than condition 1 or 2). To save these exclusion changes, hit the Save button. This will create a corresponding LOG file in the same folder as the MT file, which stores information about which trajectories have been converted into the manual-exclusion condition 888 (and if the option is set, which trajectories have been converted into systematic-exclusion condition 666). When loading the MT file(s) later, it will ask you whether you would like to load LOG files as well. When a LOG file has been loaded with an MT file, it is indicated by a “[*]” appended to the end of the MT file in the file list on the left side of the window.

If you right click on the Condition 1 pane or Condition 2 pane, you can export all the trajectories in that pane into a .CSV file for immediate reading in Excel. This exporting comes in a vertical format that makes it extremely easy to draw an Excel scatterplot of every single trajectory in the condition.

After hitting Exclude, a message box will then prompt you to re-visualize the trajectories. Indicating yes will re-visualize trajectories and the selected trajectory item(s) that you excluded should now disappear from the Condition 1 and 2 panes.


Step 4: Computing and outlier screening

Hit the Compute button. MouseTracker computes two measures of spatial attraction toward the opposite response alternative: maximum deviation (MD) and area-under-the-curve (AUC). See About MouseTracker Data | Measuring Attraction. you press this button, the mean MD and AUC values for Condition 1 and Condition 2 will appear above the mean trajectory pane. Although MD and AUC is calculated for every unselected response alternative for every trial, the mean values reflect the default comparison response alternative that was specified in the default-compare column of the experiment .CSV file. If this is not useful for you, all the MD and AUC values for each trial (if there are more than 2 response alternatives) is provided in the export .CSV file. Also included in the export .CSV file is an MD_time measure. This is simply the time in milliseconds at which point a trajectory maximally deviates toward another response alternative (i.e., MD).

The Compute button also generates a measure of motor complexity: x-flips (XF) and y-flips (YF), which are the amount of reversals along the x-axis and y-axis, respectively. They reflect a trajectory’s fluctuation between response alternatives. You can set the minimum/maximum size of a change along the x-axis and y-axis that qualifies as an x-flip or y-flip, respectively, using the Settings button.

After hitting the Compute button, MouseTracker will prompt you about whether you would like to conduct outlier screening. If you hit Yes, the following screen will appear:

First, you select which measure(s) you would like to use to define outliers. Options include: MD, AUC, XF, YF, IT, and RT (see left). You can select only one measure or you can select multiple ones.

You also need to specify how many SDs away from the mean constitutes an outlier, and whether you would like to define outliers as larger than the SD threshold in the positive direction (Greater than) or smaller than the SD threshold in the negative direction (Less than), or both. If the outlier threshold were 3 SD, then selecting Greater than would screen out trajectories whose data is greater than M + 3 SD and selecting Less than would screen out trajectories whose data is less than M - 3 SD.

Lastly, you need to choose whether to Screen across all subjects (M and SD are averaged across all subjects) or to Screen separately for each subject (M and SD are averaged separately for each subject). The M and SD are always averaged across both Condition 1 and 2.

As an example, given the options selected on the screen on the left, MouseTracker would compute means across all subjects, and then screen based on MD, AUC, and RT. If a trial's MD, AUC, or RT exceeded 3 SD above the mean of the respective measure (the mean averaged across all subjects), then it would be screened out. 

Once you hit Go, all trajectories screened out will be re-coded to condition 666 (rather than 1 or 2). MouseTracker will then prompt you about re-visualizing. Hit Yes to re-visualize trajectories; if trajectories were extreme enough to exceed your threshold, then they should disappear from the Condition 1 and 2 panes upon re-visualization.

Whether this systematic screening is saved to .LOG files (just like manual exclusions are) is optional (set using the Settings button).


Hitting the Compute button also generates two z-normalized values of the MD and AUC of all trajectories in Condition 1 and 2, which are useful for distributional analyses. One z-normalized value comes from pooling across both Condition 1 and 2 (“together”) and another ­z-normalized value comes from pooling separately within Condition 1 and within Condition 2 (“separate”). These z-normalized MD and AUC values appear in the exported .CSV data sheet. Again, this is only done for MD and AUC values coming from the default-compare response alternative.

By right-clicking on the Condition 1 or Condition 2 pane, you can also run a Distributional Analysis. A screenshot of such an analysis is below. A histogram is depicted, showing the z-normalized MD or AUC values of trajectories in Condition 1 or Condition 2 (using the "together" normalization, see above). To modify the histogram properties, change the # Bins slider (to change the number of bins in the histogram) and the Z range slider (to change the max/min z values in the histogram). For instance, if the total number of bins is set to 40 and the z range is set to 3 (as done below), 40 bins ranging from -3 to 3 will be included in the histogram. To analyze MD, select the MD option, and to analyze AUC, select the AUC option. Computed values for the distribution's Skewness, Kurtosis, N, and Bimodality are included on the right. For more information about distributional analyses and the bimodality coefficient (b), see the About MouseTracker Data | Distributional Analysis section.

If you opted to conduct a raw time analysis, MD, AUC, x-flips, y-flips are not computed. Rather, velocity, acceleration, and angle profiles are generated and these are displayed in a new window after clicking the Compute button. It will first prompt you whether you would like to compute velocity/acceleration based on x,y-coordinates, just x-coordinates, or just y-coordinates. This information also appears in the output .CSV file.


Step 5: Exporting data to .CSV file

Finally, hit the Export to .CSV button. This exports all of the data to a .CSV file readable in Microsoft Excel. It will prompt you for what path and name you would like to save the .CSV file as saves. It will then automatically load this file in your default application associated with .CSV files (probably Microsoft Excel) for you to inspect it immediately.