Attempting to replicate your experiment for Albanian – Issues running locally

[amina-crypto]

I hope this message finds you well.

My name is Amina Ademi I am a Software Engineer with 2 years of experience and a master student. I am currently working on my Master's thesis, inspired by the paper linked in your GitHub repository. I am deeply interested in the webcam-based eye-tracking experiment you have created. Having studied the paper in detail, I am aiming to replicate the same experiment but with a key variation: I plan to conduct it in the Albanian language.

The goal of my research is to compare the eye-movement patterns observed during reading in:

The native language (Albanian),

A non-mother tongue language (English),
and analyze how reading comprehension and visual attention differ across languages.

📌 What I Have Done So Far:
✅ Studied the original paper and understood the experimental setup and methodology.

✅ Cloned the GitHub repository to my local machine.

✅ Attempted to run the project locally, but faced issues getting it to work.

✅ Tried deploying it on Heroku, since the repo contains a Heroku folder:

Resolved multiple issues related to library version mismatches between the project and Heroku’s build environment.
Ultimately, I was blocked due to Heroku's 500 MB slug size limit.
Could you kindly advise me on how to run the experiment locally on my machine?

Any setup instructions, dependencies, or required services would be extremely helpful. I am very committed to replicating this work as a foundation for my own thesis and would deeply appreciate any support or direction you could offer.

Thank you in advance for your time and for sharing such impactful research publicly.

Warm regards,
Amina Ademi

[tfnribeiro]

Hello Amina,

I am happy to hear about your interest in this project, and I wish you the best of luck with your own research!

Regarding the setup, you can try to create a psiTurk (https://psiturk.readthedocs.io/en/stable/quickstart.html) locally, however that won't allow you to share the experiments with participants, however that should allow you to test your own version of the experiment. With my current experience, I would have probably created a docker container with the experiment, making it easier to publish and share in a public server.

When we deployed using Heroku, we were using a paid tier, I believe the slug size in that tier was up to 2GBs.

If you are not planning to use AmazonTurk, you could also just attempt to serve the jsPsych experiment, and then store the data using their framework.

Let me know if that helps!

Kind Regads,
Tiago

[amina-crypto]

Hi Tiago,

Thank you so much for your detailed and helpful response!

I’ll definitely try setting up psiTurk locally as you suggested and will also explore the idea of creating a Docker container — that sounds like a great solution for making everything easier to manage and share later on. Thanks as well for explaining about the Heroku setup and the slug size; that really clears things up.

I really appreciate your help! I’ll give these steps a try, and if I run into any issues along the way, I hope you won’t mind if I reach out again.

Kind regards,
Amina

[amina-crypto]

Hi Tiago,

I finally managed to run the project locally inside a Docker container. I built the image and container and proceeded with the Albanian language classes. I’m now trying to replicate one English experiment locally, following the README:

I opened root/generate_set/pilot_webgazer_experiment_dev_[LANG].html, set the viewport to 1280×720 in devtools, skipped through the experiment, and downloaded the images plus the .CSV.

I copied all generated files into root/scripts/experiment_data/[FOLDER_NAME].

I ran root/scripts/experiment.py [FOLDER_NAME] (README mentions expriment.py—I used experiment.py if present), which created the JS trials and I verified image names are 1280×720 and match the CSV.

I took the latest HTML template, updated:

set_name = "[FOLDER_NAME]"

the trials include file

the timeline

the preload list

all <script src="..."> paths to be correct

I ran root/scripts/study.py [FOLDER_NAME], generated word_boundaries.csv, and the script loaded the data.
However, when I try to open the experiment HTML (also tried the ones inside scripts/experiment_data/m_turk_EN_v0X/), I get a blank page. The Python HTTP server only shows a 404 for favicon.ico; other assets return 200/304. I still see a blank page and the same behavior.

Could you point me to the minimal HTML/script order and expected file locations for the generated reconstruct_trials_[FOLDER_NAME].js (or equivalent)? Also, is the correct generator script name experiment.py or expriment.py in this repo?

If helpful, I can share:

The exact folder tree under scripts/experiment_data/[FOLDER_NAME]

The <script> tags from my HTML

The browser Console stack traces.I will attach some photos here of my current situation.

and the view from inside the folder of the experiment that I am trying to do:

and the view from the console:

I have arrived to the point , where I get the instructions from the camera to be opened and click to begin the experiment , but then it appears only a blank screen and it is frozen there.

Can you please provide me with some hints on how to solve this situation?
Thanks a lot!

Best,
Amina

[tfnribeiro]

Hello Amina,

Could you point me to the minimal HTML/script order and expected file locations for the generated reconstruct_trials_[FOLDER_NAME].js (or equivalent)? Also, is the correct generator script name experiment.py or expriment.py in this repo?

The script is experiment.py (there was just a typo in the README) thanks for pointing that out.

So, I never built a docker container, and I have always run the experiment via Psiturk installed on the machine. Looking at the screenshots it seems you are quite close.

I can see the CSS is not loaded, so I suspect there is something happening with loading some of the Javascript from JsPsych in this case.

You said you have setup the experiment using docker, but how are you running the webserver? I'd recommend you take a look at the HerokuCode folder, and that contains what the Webserver ran for the experiments done in Mturk.

From the URL in your browser, it seems you are trying to launch the experiment / serve the page from the scripts folder.

My suggestion is that you try to replicate in your docker container the HerokuCode/heroku-webgazer structure, updating the files:

• static/image/mturk_EN_v20
• templates/pilot_webgazer_experiment_mturk_EN_v20.html

To the files you have created / your own experiment.

The docker should essentially get the heroku-webgazer and serve the app on 8080 (after running herokuapp.py). I assume this should work, but I never tested it myself.

Hope it helps. Cheers,
Tiago