Skip to main content

Decides whether given gaze points represent a saccade, fixation, or some unknown pattern

Project description

The Python package gazeclassifier provides functions to decide if given gaze points represent a saccade, fixation, or some unknown pattern.

The package gazeclassifier is developed at Infant Cognition Laboratory at University of Tampere.

1. Install

With pip:

$ pip install gazeclassifier

Compatible with Python 2.6, 2.7, 3.3, 3.4, and 3.5.

2. Usage

Import the lib:

>>> import gazeclassifier as gaze

Define gaze points as pointlists:

>>> g1 = [[0,0], [0,0], [1,1], [2,2], [2,2]]  # a saccade
>>> g2 = [[1,1], [1,1], [1,1], [1,1], [1,1]]  # a fixation
>>> g3 = [[1,1], [2,2], [0,0], [4,4], [1,1]]  # an unknown

Create a classifier. It is already pretrained and therefore able to predict:

>>> gc = gaze.GazeClassifier()
>>> gc.predict(g1)
'saccade'
>>> gc.predict(g2)
'fixation'
>>> gc.predict(g3)
'unknown'

Internally, predict first extracts features from pointlists before classification. The features can be extracted explicitly with extract_features and extract_raw_features:

>>> gaze.extract_features(g1)
{
  'saccade_reaction': 1,
  'saccade_duration': 3,
  'saccade_mse': 0.000623,
  'fixation_mse': 0.232406
}

>>> gaze.extract_raw_features(g1)
{
  'saccade': {
    'source_points': [[0,0]],
    'saccade_points': [[0,0], [1,1], [2,2]],
    'target_points': [[2,2]],
    'mean_squared_error': 0.000623
  },
  'fixation': {
    'centroid': [[1.0,1.0]]
    'mean_squared_error': 0.232406,
  }
}

As an alternative for using the default pretrained classifier, you can train one:

>>> training_data = [g1, g2, g3]
>>> classes = ['saccade', 'fixation', 'unknown']
>>> gc = gaze.GazeClassifier()
>>> gc.fit(training_data, classes)

The trained classifier has same API as the default:

>>> gc.predict(g1)
'saccade'

3. API

3.1. gazeclassifier.predict(pointlist)

Parameters:

  • pointlist: a list of [x, y] points i.e. a list of lists

    • OR alternatively the result dict from extract_features. This is convenient if you need access to the features and want to prevent predict to re-extract them.

Return a string which can be one of the following:

  • 'saccade': gaze travels from point A to B and otherways stays still

  • 'fixation': gaze has mainly stayed still

  • 'unknown': gaze cannot be regarded as any of the above

3.2. gazeclassifier.extract_features(pointlist)

Parameters:

  • pointlist: a list of [x, y] points i.e. a list of lists

Return a dict that contains mean error and details for each hypothesis. The dict can be fed into classify for classification.

3.3. gazeclassifier.extract_raw_features(pointlist)

Parameters:

  • pointlist: a list of [x, y] points i.e. a list of lists

Return a dict that contains mean error and details for each hypothesis. The dict can be fed into predict for classification.

3.4. gazeclassifier.GazeClassifier()

A new untrained classifier.

3.5. gazeclassifier.GazeClassifier#fit(pointlists, classes)

3.6. gazeclassifier.GazeClassifier#predict(pointlist_or_features)

3.7. gazeclassifier.version

The current version string:

>>> gazeclassifier.version
'1.2.3'

4. For developers

Tips for the developers of the package.

4.1. Use Git

To develop, clone the repository from GitHub:

$ git clone https://github.com/infant-cognition-tampere/gazeclassifier-py

Make changes to files, add them to commit, and do commit:

(edit README.rst)
$ git add README.rst
$ git commit -m "Improved documentation"

List files that are not added or not committed:

$ git status

Push local commits to GitHub:

$ git push

Ignore some files by editing .gitignore:

$ nano .gitignore

4.2. Virtualenv

Manage python versions and requirements by using virtualenv:

$ virtualenv -p python3.5 gazeclassifier-py
$ cd gazeclassifier-py
$ source bin/activate
...
$ deactivate

4.3. Testing

Follow instructions to install pyenv and then either run quick tests:

$ python3.5 setup.py test

or run comprehensive tests for multiple Python versions listed in tox.ini:

$ pyenv local 2.6.9 2.7.10 3.3.6 3.4.3 3.5.0
$ eval "$(pyenv init -)"
$ pyenv rehash
$ tox

Install new pyenv environments for example by:

$ pyenv install 3.5.0

Validate README.rst at http://rst.ninjs.org/

4.4. Publishing to PyPI

Follow python packaging instructions:

  1. Create an unpacked sdist: $ python setup.py sdist

  2. Create a universal wheel: $ python setup.py bdist_wheel --universal

  3. Go to PyPI and register the project by filling the package form by uploading gazeclassifier.egg-info/PKG_INFO file.

  4. Upload the package with twine:

    1. Sign the dist: $ gpg --detach-sign -a dist/gazeclassifier-1.2.3*

    2. Upload: twine upload dist/gazeclassifier-1.2.3* (will ask your PyPI password)

  5. Package published!

Updating the package takes same steps except the 3rd.

4.5 Version release

  1. Change version string in gazeclassifier/version.py and setup.py to '1.2.3'

  2. Run tox tests. See 4.3. Testing.

  3. Git commit: $ git commit --all -m "v1.2.3 release"

  4. Create tag: $ git tag -a 1.2.3 -m "v1.2.3 stable"

  5. Push commits and tags: $ git push && git push --tags

  6. Publish to PyPI. See 4.4. Publishing to PyPI.

5. Versioning

Semantic Versioning 2.0.0

6. License

MIT License

Project details


Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page