mirror of
https://github.com/adswa/multimatch_gaze.git
synced 2026-06-22 20:13:40 +00:00
150 lines
No EOL
8.2 KiB
Markdown
150 lines
No EOL
8.2 KiB
Markdown
[](https://travis-ci.com/adswa/multimatch_gaze)
|
||
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
|
||
[](#contributors-)
|
||
<!-- ALL-CONTRIBUTORS-BADGE:END -->
|
||
[](https://codecov.io/gh/adswa/multimatch_gaze)
|
||
[](https://multimatch.readthedocs.io/en/latest/)
|
||
[](https://badge.fury.io/py/multimatch-gaze)
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://ci.appveyor.com/project/adswa/multimatch_gaze)
|
||
[](https://zenodo.org/badge/latestdoi/151181532)
|
||
[](https://doi.org/10.21105/joss.01525)
|
||
[](https://datalad.org)
|
||
|
||
|
||
|
||
# multimatch-gaze
|
||
## Reimplementation of MultiMatch toolbox (Dewhurst et al., 2012) in Python.
|
||
|
||
The **MultiMatch** method proposed by Jarodzka, Holmqvist and Nyström (2010),
|
||
implemented in Matlab as the MultiMatch toolbox and validated by Dewhurst
|
||
and colleagues (2012) is a vector-based, multi-dimensional approach to
|
||
compute scan path similarity.
|
||
|
||
For a complete overview of this software, please take a look at the
|
||
[Documentation](https://multimatch.readthedocs.io/en/latest)
|
||
|
||
The method represents scan paths as geometrical vectors in a two-dimensional
|
||
space: Any scan path is build up of a vector sequence in which the vectors
|
||
represent saccades, and the start and end position of saccade vectors represent
|
||
fixations. Two such sequences (which can differ in length) are compared on the
|
||
five dimensions **'vector shape'**, **'vector length'** (saccadic amplitude),
|
||
**'vector position'**, **'vector direction'** and **'fixation duration'** for a
|
||
multidimensional similarity evaluation (all in range [0, 1] with 0 denoting
|
||
maximal dissimilarity and 1 denoting identical scan paths on the given measure).
|
||
The original Matlab toolbox was kindly
|
||
provided via email by Dr. Richard Dewhurst and the method was ported into Python
|
||
with the intent of providing an open source alternative to the matlab toolbox.
|
||
|
||
### Installation instructions
|
||
|
||
It is recommended to use a dedicated virtualenv:
|
||
|
||
# create and enter a new virtual environment (optional)
|
||
virtualenv --python=python3 ~/env/multimatch
|
||
. ~/env/multimatch/bin/activate
|
||
|
||
multimatch-gaze can be installed via pip. To automatically install multimatch-gaze with all
|
||
dependencies ([pandas](https://pandas.pydata.org/), [numpy](https://www.numpy.org/),
|
||
[scipy](https://www.scipy.org/) and
|
||
[argparse](https://docs.python.org/3/library/argparse.html)), use:
|
||
|
||
# install from pyPi
|
||
pip install multimatch-gaze
|
||
|
||
|
||
### Support/Contributing
|
||
|
||
Bug reports, feedback, or any other contribution are always appreciated.
|
||
To report a bug, request a feature, or ask a question, please open an
|
||
[issue](https://github.com/adswa/multimatch_gaze/issues/new).
|
||
[Pull requests](https://help.github.com/en/articles/creating-a-pull-request-from-a-fork)
|
||
are always welcome. In order to run the test-suite of ``multimatch-gaze`` locally,
|
||
use [pytest](https://docs.pytest.org/en/latest/), and run the following command in the
|
||
root of the repository:
|
||
|
||
``python -m pytest -s -v``
|
||
|
||
For additional information on how to contribute, checkout
|
||
[CONTRIBUTING.md](https://github.com/adswa/multimatch_gaze/blob/master/CONTRIBUTING.md).
|
||
|
||
|
||
### Examplary usage of multimatch-gaze in a terminal
|
||
|
||
**required inputs:**
|
||
- two tab-separated files with nx3 fixation vectors (x coordinate in px, y coordinate in px, duration)
|
||
- screensize in px (x dimension, y dimension)
|
||
|
||
`` multimatch-gaze data/fixvectors/segment_10_sub-19.tsv data/fixvectors/segment_10_sub-01.tsv 1280 720 ``
|
||
|
||
|
||
|
||
**optional inputs:**
|
||
|
||
if scan path simplification should be performed, please specify in addition
|
||
- --amplitude-threshold (-am) in px
|
||
- --direction-threshold (-di) in degree
|
||
- --duration-threshold (-du) in seconds
|
||
|
||
Example usage with grouping:
|
||
|
||
`` multimatch-gaze data/fixvectors/segment_10_sub-19.tsv
|
||
data/fixvectors/segment_10_sub-01.tsv 1280 720 --direction-threshold 45.0
|
||
--duration-threshold 0.3 --amplitude-threshold 147.0 ``
|
||
|
||
**REMoDNaV helper:**
|
||
|
||
Eye movement event detection results produced by [REMoDNaV](https://github.com/psychoinformatics-de/remodnav)
|
||
can be read in natively by multimatch-gaze. To indicate that datafiles are REMoDNaV outputs, supply the
|
||
``--remodnav`` parameter.
|
||
|
||
`` multimatch-gaze data/remodnav_samples/sub-01_task-movie_run-1_events.tsv
|
||
data/remodnav_samples/sub-01_task-movie_run-2_events.tsv 1280 720 --remodnav ``
|
||
|
||
REMoDNaV can classify smooth pursuit movements. As a consequence, when using REMoDNaV output, users need to
|
||
indicate how these events should be treated. By default, multimatch-gaze will discard pursuits. In some
|
||
circumstances, however, it can be useful to include pursuit information. Moving stimuli for example would
|
||
evoke a pursuit movement during visual intake. When specifying the ``--pursuit keep`` parameter, the start
|
||
and end points of pursuits will be included in the scan path.
|
||
|
||
`` multimatch-gaze data/remodnav_samples/sub-01_task-movie_run-1_events.tsv
|
||
data/remodnav_samples/sub-01_task-movie_run-2_events.tsv 1280 720 --remodnav --pursuit keep``
|
||
|
||
|
||
### References:
|
||
|
||
Dewhurst, R., Nyström, M., Jarodzka, H., Foulsham, T., Johansson, R. &
|
||
Holmqvist, K. (2012). It depends on how you look at it: scanpath comparison in
|
||
multiple dimensions with MultiMatch, a vector-based approach. Behaviour Research
|
||
Methods, 44(4), 1079-1100. [doi: 10.3758/s13428-012-0212-2.](https://doi.org/10.3758/s13428-012-0212-2)
|
||
|
||
Dijkstra, E. W. (1959). A note on two problems in connexion withgraphs.
|
||
Numerische Mathematik, 1, 269–271. [https://doi.org/10.1007/BF01386390](https://doi.org/10.1007/BF01386390)
|
||
|
||
Jarodzka, H., Holmqvist, K., & Nyström, M. (eds.) (2010). A vector-based,
|
||
multidimensional scanpath similarity measure. In Proceedings of the 2010
|
||
symposium on eye-tracking research & applications (pp. 211-218). ACM.
|
||
[doi: 10.1145/1743666.1743718](https://doi.org/10.1145/1743666.1743718)
|
||
|
||
|
||
## Contributors ✨
|
||
|
||
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
|
||
|
||
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
|
||
<!-- prettier-ignore-start -->
|
||
<!-- markdownlint-disable -->
|
||
<table>
|
||
<tr>
|
||
<td align="center"><a href="http://www.onerussian.com"><img src="https://avatars3.githubusercontent.com/u/39889?v=4" width="100px;" alt=""/><br /><sub><b>Yaroslav Halchenko</b></sub></a><br /><a href="#ideas-yarikoptic" title="Ideas, Planning, & Feedback">🤔</a></td>
|
||
<td align="center"><a href="http://psychoinformatics.de"><img src="https://avatars1.githubusercontent.com/u/136479?v=4" width="100px;" alt=""/><br /><sub><b>Michael Hanke</b></sub></a><br /><a href="https://github.com/adswa/multimatch_gaze/commits?author=mih" title="Code">💻</a></td>
|
||
<td align="center"><a href="https://github.com/mflan48"><img src="https://avatars3.githubusercontent.com/u/46726614?v=4" width="100px;" alt=""/><br /><sub><b>mflan48</b></sub></a><br /><a href="https://github.com/adswa/multimatch_gaze/commits?author=mflan48" title="Code">💻</a> <a href="https://github.com/adswa/multimatch_gaze/issues?q=author%3Amflan48" title="Bug reports">🐛</a></td>
|
||
<td align="center"><a href="https://github.com/LFaggi"><img src="https://avatars1.githubusercontent.com/u/73990795?v=4" width="100px;" alt=""/><br /><sub><b>LFaggi</b></sub></a><br /><a href="https://github.com/adswa/multimatch_gaze/commits?author=LFaggi" title="Code">💻</a> <a href="https://github.com/adswa/multimatch_gaze/issues?q=author%3ALFaggi" title="Bug reports">🐛</a></td>
|
||
</tr>
|
||
</table>
|
||
|
||
<!-- markdownlint-enable -->
|
||
<!-- prettier-ignore-end -->
|
||
<!-- ALL-CONTRIBUTORS-LIST:END -->
|
||
|
||
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! |