Getting Started with iTrace Toolkit v0.1.0

Basic Usage:

  1. Create a new or load and existing iTrace sqlite database
  2. Import iTrace XML Data (from Core/Plugin)
  3. Perform Token Analysis (optional)
  4. Run Fixation Filters
  5. Run Fixation Highlighting (optional)

Before You Begin

iTrace Toolkit v0.1.0 is only compatible with data generated by version 0.1.0 of iTrace Core, iTrace Visual Studio Plugin, and iTrace Eclipse Plugin. Data generated by older versions of these tools are NOT COMPATIBLE.

Database Creation and Loading

In order to perform post processing on your iTrace XML data files it is necessary to create a new sqlite database or open an exiting database. To create a database click the Create New Database button on the Database window tab. In the new window that opens you can browse for the directory to save the database and enter a name for the file. If you already have a sqlite database file, you can click the Browse for Existing Database button and the Database window tab and use the file browser to locate your database.

Once you have chosen to create a database or browse for an existing one, simply click Load Database to open and prepare the database for use.

Importing iTrace XML Data Files

With the database loaded, choose the Import XML window tab to begin importing iTrace Core or Plugin XML data files. Simply use the Browse for iTrace XML button to launch the file browser and select your input file. With a file selected, you can then click the Import XML Data button to import the data into your database file. This will need to be repeated for each file you wish to import, but only needs to be done once per database file. To avoid duplicate imports of XML data files, each import file will be compared against a hash value (SHA 1) of existing imported data files and reject any file hash that matches a previously imported file.

Token Analysis

If you have srcML format XML documents of the source code used during a study, it is possible to use the Token Analysis window tab to automatically have source code token information added to your database file. To load a srcML file for token analysis, use the Browse for srcML Archive button to located your srcML file and click Identify Tokens to begin mapping tokens to gazes in the database.

Creating srcML XML

To perform token analysis tasks with iTrace Toolkit it is necessary to provide an XML marked up version of the source code under study using srcML (v1.0 or higher only). This can be done with the following command: srcml [source code] --position -o output.xml In the command above, source code can be individual files, a directory, a compressed archive, or any combination of the three. The position option addes details concerning line and column information of the original source code. If there are issues with position data encoded into the output XML such as invalid positions, you can supplement the above command with the option --jobs 1 which may resolve the issue. For additional information about srcml, please visit https://www.srcml.org/

Fixation Filtering

To perform fixation calculation on your dataset, select the Fixation window tab. The fixation algorithm dropdown list contains the three currently supported fixation approaches. Selecting an algorithm changes the parameters that can be configured for fine tuning the algorithms. Clicking Generate Fixation Data to run the fixation algorithm. All fixation runs are recorded in the same database for later querying/analysis. Fixations are currently run in groups based on the session (all gazes recorded between the start and stop of a tracker using iTrace Core).

Fixation Highlighting

iTrace Toolkit can output HTML versions of the source code with tokens associated with each fixation highlighted. This is done per fixation calculation and output into a folder named after the ID number of the fixation processing run (timestamp recorded by iTrace Toolkit).

Output Artifacts:

  • A complete sqlite3 database containing:
    • All raw data
    • Source code tokens and syntactic context (using a srcML XML document)
    • Fixations associated with each raw gaze data point
    • Calibration information
    • Recording session metadata and participant information (non-identifiable)
  • HTML files representing the source code with fixation tokens highlighted

Important Notes:

Some tasks such as token analysis are computationally expensive. The UI will be unavailable for interaction until the processing task is finished. Completion of a processing task is indicated by the status bar of the application displaying the text Ready.