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.
With pip:
$ pip install gazeclassifier
Compatible with Python 2.6, 2.7, 3.3, 3.4, and 3.5.
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'
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 preventpredict
to re-extract them.
- OR alternatively the result dict from
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
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.
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.
A new untrained classifier.
The current version string:
>>> gazeclassifier.version
'1.2.3'
Tips for the developers of the package.
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
Manage python versions and requirements by using virtualenv:
$ virtualenv -p python3.5 gazeclassifier-py
$ cd gazeclassifier-py
$ source bin/activate
...
$ deactivate
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/
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)
- Sign the dist:
- Package published!
Updating the package takes same steps except the 3rd.
- Change version string in
gazeclassifier/version.py
andsetup.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.