Add a parser (or use existing one if possible) for reading data from the following dataset: https://dl.acm.org/doi/fullHtml/10.1145/3448018.3457420

Requirements:
Create a Jupyter Notebook to show that all functions and methods work with the new dataset.
Add dataset and reference to the dataset dictionary in the code.
Make sure dataset can be downloaded automatically and unzipped using existing methods.

In the read_EyeLink1000 function, fixations, saccades, and blinks were parsed into the samples variable. An example can be seen below:

The same token that is used to populate the fields of the Fixation object was also appended into samples. If the Al Madi 2018 dataset does not have raw samples, the samples variable should be kept empty to avoid any confusion.

add progress bar to do dataset download and unzip feature

Instead of downloading the toolkit and all the datasets, it would be better to automatically download the specific dataset when it is used. This is the common convention in NLTK.

The dimensions used for pasting the stimuli onto the background are incorrect:

Instead of (100, 375), they should be (0, 375) to allow users to see correct positions of fixations on the text.

We wanted to be more specific with the names of two parsers, so we decided to change the name from read_FileType to read_EyeTrackerName, and add the file type as a parameter.

the function add_tokens_to_AOIs does not work when AOI kind is set to "line" it only works when kind is set to "sub-line"

Create parsers for 3 datasets from eyeCode, a tool similar to emtk, written in Python 2. The datasets can be found here: https://github.com/synesthesiam/eyecode/tree/master/data.

EMTK doesn't have a community profile yet, so it is not clear how people can contribute to the open-source project. To help build a community around the tool, we need a few well written documents. You can contribute these documents by looking up tutorials and checking the repositories of popular open-source projects. The documents we need are:

1- Code of conduct
2- Contributing
3- License
4- Issue templates
5- Pull request template

At line 69 of idt_classifier.py, it should be
[timestamp, len(window_x) * sample_duration, statistics.mean(window_x), statistics.mean(window_y)])
not
[timestamp, len(window_x) * 4, statistics.mean(window_x), statistics.mean(window_y)])

In draw_trial method of Trial class:

With the background-size:

I suggest saving them as fields of the Experiment class instead of declaring them arbitrarily without any context because the coordinates of the Fixations depend on the background-size and the trial location.

So far we have been using the example notebooks as tests, but it would be much better to develop unit tests for every method in the toolkit. Maybe consider automating the testing process on GitHub to make collaboration and onboarding easier.

For the sake of testing ideas like fixation correction, it would be great to be able to generate a "synthetic" eye movements according to some model or maybe completely random.

This can be used for testing code and demonstrating features as well.

Initially, we chose inheritance for class design. Every eye movement element was modeled as a super class, while the subclasses being the specific eye movements from various types of eye trackers. However, we think it would make it difficult when we add support for more types of eye trackers in future development. Now, @sdotpeng will eliminate inheritance in our program, making universal class of eye movement for various eye trackers.

Something similar to https://github.com/sympy/sympy would be good.

This includes creating a "Contributing" page, "Adding dataset" page, and the a "Documentation Style Guide" page

These functions manually matches the name of the stimuli with the name of the original code file, from which the stimuli was adapted. An example can be seen below (this is taken from add_tokens_to_AOIs):

This needs to be refactor to make the two functions extendable for future datasets.

Initially we had a function get_sample_number to returns the total number of eye movements. Later, we decided to store the raw sample in the Trial class. Thus, this function should now return the number of raw samples, while another function called get_eye_movement_number can do the first job.

The add_srcML currently uses pre-generated files for the EMIP dataset code. It does not generate srcML tags for any piece of code.

It would be great to integrate srcML into the tool so it is called automatically (behind the scene) to generate the srcML tags for any code, then add the tags to the dataframe.

This means that we will add srcML as a dependency, so let's see if we can do this in an easy way. Not sure if srcML is downloadable through pip or similar. This might create problems for our automated Action testing, if srcML is not downloadable through pip.

A good start would be at srcML website to understand the tool and how it works: https://www.srcml.org/

The AlMadi2018 dataset citation link is broken.

Here's the broken link: https://dl.acm.org/doi/10.1145/3448018.345742

This link should probably lead to this paper: https://ieeexplore.ieee.org/document/8334439

An automated web documentation for EMTK would make it easier to understand methods and functions. Also, it would provide a helpful reference for tool users.

Since we decided to remove inheritance and use universal class for eye movement #7, we have to adapt the code that allows empty attributes, in those situation where one type of eye tracker doesn't record one or more types of eye movement. @sdotpeng is in charge.

Hi @nalmadi,
Ideally we want to provide users with more fixation detection methods. Other than the dispersion-based, we can, for example, use the 10 methods benchmarked in this paper https://link.springer.com/content/pdf/10.3758/s13428-016-0738-9.pdf. Also it would be useful if we can add more documents for this one.

Initially, we implemented the reset offset method to undo all applied offset. However, there seems to be a tiny bug where offset was not corrected reset.

Initially, there was only EMIP dataset. After we added some dataset from Eye Link 1000, we found out that the organization of each dataset is different. We now want to add datasets in one directory called "datasets", and we will separate each into a folder.

In future development, we will write up instructions for importing dataset.

When the download function below

used to download the EMIP dataset, it also downloads the published version of this toolkit and the corrected dataset into the datasets folder. Is this a desirable feature? I believe that it should only download the raw data.

Referring to #9, we need to separate the fixation_filter method into two methods. We need to create a method for SMI Red 250 parser that removes the invalid samples.

Move the corrected EMIP dataset to the datasets directory.

Make the dataset readable by the toolkit by creating a simple parser for it.

im = EMIP[subject_ID].trial[trial_num].draw_trial(image_path, draw_raw_data=False, draw_fixation=True, draw_saccade=False, draw_number=True, draw_aoi=True)

When draw_saccade is set to true it gives an error claiming a font is missing

Since we decided to eliminate inheritance in #7, we now needed to add an attribute in the Trial class to distinguish among different types of eye trackers.

Since multiple classes are being merged into one, the implementation of the draw_trial should not make assumptions about the specific trial it is drawing. Initially we wanted to create a unified visualization style, but that might not work for every trial since variations in background colors and style are possible. Instead, we want the draw_trial method to allow the user to customize the visualization with various color and style options.

Upgrade Pillow to version 8.2.0 or later. For example:

Pillow>=8.2.0

In the draw_trial method of the Trial class:

This line of code pastes an image in the AlMadi 2018 runtime dataset (an image with white text and transparent background), hereafter referred to as "the image", into a black background, hereafter referred to as "this feature":

1st Question: How does converting the image into RGBA and using it as a mask image manage to achieve this feature?

My expectation is that to achieve this feature, we only need to paste the image on top of the black background without having to use any mask image:

background.paste(im.convert('RGBA'), trial_location)

Because the background of the image is already transparent, and the word is white, contrast with the black background. However, what I get is a completely white box on a black background:

2nd Question: Why the line of code I wrote fail to achieve this feature?

Here is full code I used to test both ways:

    image_path = "EMIP-Toolkit/datasets/AlMadi2018/runtime/images/5667346413132987794.png"
    im = Image.open(image_path)

    background_size = (1024, 768)
    background = Image.new( 'RGBA', background_size, color='black' )

    trial_location = (10, 375)

    # background.paste( im, trial_location, im.convert('RGBA') )
    background.paste( im.convert('RGBA'), trial_location )
    background.save("result.png")
    
    im = background.copy()
    im.show()

The samples field of the Trial class stores the raw samples from datasets. The field is currently a list of samples, with each sample represented by another list. The field should be, however, a dataframe, with each row corresponding with one sample, or a list of objects, with each object corresponding with one sample. This way, it will be clearer what features each sample has.

Represent each sample with a list can lead to the use of magic numbers to access sample's information. An example can be seen below:

Initially, the parser methods were in the Dataset class. Since we decided to remove inheritance and also cut off this class, all parser methods become free functions now. Name of the eye trackers needs to be included.

Initially the function fixation_filter in the Trial class removes invalid samples and classifies fixations based on I-DT algorithm. Now, we want to divide the tasks so that idt_classifier does only classifying job, while adding one more free function that only removes the invalid samples.

Add a new visualization to generate a video of a trial based on stimuli image and fixation (and possibly saccades) timestamps. The fixation position should appear as a circle and the video should be in real time (not faster/slower than recording).