Metadata-Version: 2.0
Name: sideeye
Version: 1.0.0a3
Summary: Library for analyzing eye-tracking-while-reading data
Home-page: https://github.com/zediski/sideeye
Author: Amanda Doucette
Author-email: amandakdoucette@gmail.com
License: MIT
Keywords: eyetracking eye-tracking da1 psycholinguistics linguistics psychology eyetrack
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.5
Provides-Extra: dev
Requires-Dist: nose2; extra == 'dev'
Requires-Dist: pylint; extra == 'dev'
Provides-Extra: test
Requires-Dist: nose2; extra == 'test'

========
SideEye
========
|circleci| |docs|

Python package for processing eye tracking data.

Installation
------------

Dependencies
~~~~~~~~~~~~

SideEye requires Python >= 3.5.

Installation
------------------

Run the following command:

::

  pip install sideeye


The Configuration File
----------------------

The configuration file is a JSON file specifying the changeable parameters used by SideEye's default parsing and output functions. An example is found in `examples/sample_config.json <examples/sample_config.json>`_. The config file should always have the same format. It has several sections:

``da1_fields``: The locations of values in each line of a DA1 file.

``region_fields``: The locations of values in each line of a region file.

``cutoffs``: Fixation duration cutoffs.

``region_measures``: Used in region measure calculation and output.

``trial_measures``: Used in trial measure calculation and output.

``region_output``: Reported columns for region measures in output file.

``trial_output``: Reported columns for trial measures in output file.

``terminal_output``: Amount of status/debugging info to output to terminal.

da1_fields
~~~~~~~~~~

This section contains parameters needed for parsing DA1 files. Because there are several formats for DA1 files, the positions of each value in a line are needed. The parameters are all positions in a line, where 0 is the first value in the line.:

``index``: An integer identifying a single trial, usually the first number in a line.

``condition``: A value identifying the condition of the trial.

``number``: A value identifying the item of the trial.

``time``: The total time of a trial, sometimes either not included in DA1 files or at the end of every line. If this is true, this parameter should be ``-1``.

``fixation_start``: The position in a line where fixation data starts.

As an example, a line of a DA1 file could look like this:

::

  Position:   0   |   1   |   2   | 3 | 4 | 5 | 6 | 7 |   8   |   9   | ... |  -1  |
  Value:    index | cond. | num.  |   |   |   |   |   | fix.  | fix.  | ... | time |

And the ``da1_fields`` section of the config file would be:

::

  "da1_fields" : {
    "index": 0,
    "condition": 1,
    "number": 2,
    "time": -1,
    "fixation_start": 8
  }

region_fields
~~~~~~~~~~~~~

Similar to ``da1_fields``, this section specifies the positions of values in each line of a region file. The parameters are:

``number``: Item identifier.

``condition``: Item condition.

``boundaries_start``: The position where region boundaries start in a line.

``includes_y``: Whether or not the region file includes line position in region boundaries. If true, a region is bounded by four numbers: ``(char_start, line_start), (char_end, line_end)``. If false, the region is bounded by two numbers: ``char_start, char_end``.

cutoffs
~~~~~~~

This section contains cutoffs for fixations. If a fixation's duration is less than `min` or greater than `max`, it will be excluded from measure calculations.

``min``: Minimum cutoff time for fixation duration.

``max``: Maximum cutoff time for fixation duration.

``include_fixation``: When true, if a fixation is excluded by cutoffs, its duration is included in the duration of the saccade between the previous and next non-excluded fixations.

``include_saccades``: When true, if a fixation is excluded by cutoffs, the duration of the saccade into and out of the fixation is included in the saccade between the previous and next non-excluded fixations.


region_measures
~~~~~~~~~~~~~~~

This section contains parameters for region measure calculation and output. It is a list of all calculated region measure, each with two parameters:

``cutoff``: A cutoff value for the measure. If the calculated measure is greater than this value, its value in the output report is ``CUTOFF``. For some measures, where the value is not numerical, this parameter is ignored.

``include``: A boolean (true/false) value specifying whether the measure should be included in the output report. If false, the measure will be excluded.

The measures in this section of the config file are:

::

  skip
  first_pass_regressions_out
  first_pass_regressions_in
  first_fixation_duration
  single_fixation_duration
  first_pass
  go_past
  total_time
  right_bounded_time
  reread_time
  second_pass
  spillover_time
  refixation_time
  landing_position
  launch_site
  first_pass_fixation_count

trial_measures
~~~~~~~~~~~~~~

This section contains parameters for trial measure calculation and output. Each measure has the same parameters as ``region_measures``. The measures included in this section are:

::

  location_first_regression
  latency_first_regression
  fixation_count
  percent_regressions
  trial_total_time
  average_forward_saccade
  average_backward_saccade

region_output
~~~~~~~~~~~~~

This section specifies the columns that should be included in the output file for region measures. Each output column has two parameters:

``include``: Whether or not the column should be included in the output report. true/false

``header``: A title for the header of the column. Can be different from the name of the column parameter.

Columns included in this section are:

``experiment_name``: Name of experiment.

``filename``: Filename of DA1 file.

``date``: Date of DA1 file if specified, or date file was parsed if not.

``trial_id``: Trial identifier.

``trial_total_time``: Total time of trial.

``item_id``: Item identifier.

``item_condition``: Condition of item.

``region_label``: Label for region.

``region_number``: Region number (beginning with 0).

``region_text``: Text included in region, if specified.

``region_start``: Character location of beginning of region.

``region_end``: Character location of end of region.

``measure``: Name of measure.

``value``: Value of measure.

trial_output
~~~~~~~~~~~~

This section specifies the columns that should be included in the output file for trial measures. Each column has the same parameters as ``region_output``. The columns are the same, but with columns beginning with ``region_`` excluded.

terminal_output
~~~~~~~~~~~~~~~

A number specifying the level of detail in terminal output.

``0``: Errors only.

``1``: File-level information (which file is currently being parsed).

``2``: Item and trial-level parsing information.

``3``: Measure-level calculation information.

``4``: Trial-level calculation information.

``5``: All output information.

.. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest
    :alt: Documentation Status
    :scale: 100%
    :target: https://sideeye.readthedocs.io/en/latest/?badge=latest

.. |circleci| image:: https://circleci.com/gh/zediski/sideeye/tree/master.svg?style=shield
    :alt: Build Status
    :scale: 100%
    :target: https://circleci.com/gh/zediski/sideeye/tree/master


