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:
Create an unpacked sdist: $ python setup.py sdist
Create a universal wheel: $ python setup.py bdist_wheel --universal
Go to PyPI and register the project by filling the package form by uploading gazeclassifier.egg-info/PKG_INFO file.
Upload the package with twine:
Sign the dist: $ gpg --detach-sign -a dist/gazeclassifier-1.2.3*
Upload: twine upload dist/gazeclassifier-1.2.3* (will ask your PyPI password)
Package published!
Updating the package takes same steps except the 3rd.
4.5 Version release
Change version string in gazeclassifier/version.py and setup.py to '1.2.3'
Run tox tests. See 4.3. Testing.
Git commit: $ git commit --all -m "v1.2.3 release"
Create tag: $ git tag -a 1.2.3 -m "v1.2.3 stable"
Push commits and tags: $ git push && git push --tags
Publish to PyPI. See 4.4. Publishing to PyPI.
