Programming Behavioral Experiments in jsPsych

Teaching edition: October 2026. Dates and submission links are announced through the course learning platform.

Course title

Programming Behavioral Experiments in jsPsych

Instructor(s)

Bartosz Maćkiewicz

Contact details

b.mackiewicz@uw.edu.pl; consultations online via Google Meet

Affiliation

Faculty of Philosophy, University of Warsaw

Course format

Class (workshop / computer lab).

Number of hours

20 academic hours (5 meetings x 4 academic hours, i.e. 5 meetings x 180 minutes of instruction; breaks are additional).

Number of ECTS credits

2 ECTS

Brief course description

This elective introduces students to building browser-based behavioral experiments in jsPsych. Students learn how to present stimuli, collect responses, organize experiment timelines, implement randomization and counterbalancing, customize experiment appearance, and deploy studies online using JATOS and Cognition.run. The course is practical and project-based, with an emphasis on turning research questions from cognitive psychology, psycholinguistics, and related areas into runnable online studies.

Full course description

The course offers a hands-on introduction to programming behavioral experiments in jsPsych for students who already know basic programming concepts from Python or R but have no prior background in JavaScript, HTML, or CSS. The course begins with the core architecture of a jsPsych study: plugins, trials, timelines, response collection, and data output. It then moves to more realistic research designs, including blocked procedures, timeline variables, randomization, counterbalancing, conditional logic, loops, and feedback-controlled flow. Students also learn how to improve the presentation layer of an experiment through basic HTML/CSS customization and how to check practical browser and device constraints that matter in online data collection.

The final part of the course focuses on online deployment and selected advanced browser-based measures. In line with current jsPsych documentation, this includes mouse tracking and introductory webcam-based eye tracking with WebGazer, together with calibration, validation, and discussion of data-quality limits. The course also briefly introduces selected community extensions from the jsPsych ecosystem, especially examples from jspsych-contrib, such as device-motion and MediaPipe face-mesh integrations. These are presented as optional advanced examples rather than as core, fully stable competencies for a 20-hour course. By the end of the course, students should be able to design, implement, test, and deploy a small online behavioral study that is methodologically coherent and technically runnable.

Learning outcomes

After successfully completing the course, the student will be able to:

1. Explain the logic, affordances, and methodological limits of browser-based behavioral experiments implemented in jsPsych. (K_W03, K_W07)
2. Build a simple jsPsych experiment that presents stimuli, records participant responses, and exports usable behavioral data. (K_U04, K_U12)
3. Implement blocked, randomized, counterbalanced, and feedback-controlled procedures using jsPsych timelines and control flow. (K_U03, K_U04, K_U12)
4. Customize the appearance and interaction logic of an experiment with basic HTML/CSS and test it against realistic browser and device constraints. (K_U12, K_K06)
5. Critically evaluate the suitability and limitations of mouse tracking, webcam-based eye tracking, and selected community-supported motion or face-tracking extensions for a given research question. (K_W03, K_U03, K_K01)
6. Design, document, and deploy a small online study in jsPsych using JATOS or Cognition.run. (K_U02, K_U11, K_U12, K_K06)

Learning activities and teaching methods

• Short lectures introducing key concepts and methodological tradeoffs.
• Live coding during class.
• Guided hands-on exercises completed individually or in pairs.
• Reading selected sections of official documentation before or after class.
• Instructor feedback on intermediate code and design decisions.
• A final project in which each student builds and deploys a small online experiment.

List of topics/classes and bibliography

Meeting 1. From research question to first jsPsych experiment

• What jsPsych is and when it is useful.
• Minimal web stack for this course: HTML, CSS, and JavaScript for Python/R users.
• Plugins, trials, timelines, and basic response collection.
• Building and running a first experiment, then an eight-item lexical-decision pilot using a JavaScript loop.

Suggested reading:

• jsPsych Introduction
• jsPsych “Hello World” tutorial

Meeting 2. Timelines, data, and repeated experimental structure

• Timeline variables and repeated procedures.
• Randomization and sampling.
• Condition labels, accuracy, omissions, and correct-response RT.
• Inspecting, annotating, and exporting data.
• Building a parity demonstration and a Stroop classroom pilot.

Suggested reading:

• jsPsych timeline overview
• jsPsych Simple Reaction Time tutorial
• jsPsych data reference

Meeting 3. More complex designs

• Blocked designs and nested timelines.
• Counterbalancing strategies.
• Conditional branching and loops.
• Bounded practice (maximum three attempts) and conditional entry to test.
• Flanker task with independently checked central-arrow answer keys.
• First platform workflow using the already-working Meeting 2 task: local JATOS startup, study import/run, result inspection, study export/import; Cognition.run alternative.

Suggested reading:

• jsPsych timeline overview sections on conditional timelines, looping, and sampling
• Selected plugin documentation relevant to the student’s task

Meeting 4. Customization, robustness, and online readiness

• Basic HTML/CSS customization for clearer and more controlled presentation.
• Preloading and media handling.
• Browser and device constraints.
• Debugging and testing before deployment.

Suggested reading:

• jsPsych styling overview
• jsPsych browser/device support overview
• Relevant plugin pages for preload and chosen stimulus types

Meeting 5. Advanced measures, ecosystem extensions, and online deployment

• Mouse tracking in jsPsych.
• Webcam-based eye tracking with WebGazer: setup, calibration, validation, and limitations.
• Optional ecosystem examples from jspsych-contrib, such as device motion and MediaPipe face mesh, with discussion of compatibility and maintenance risks.
• Exporting and deploying experiments with JATOS and Cognition.run.
• Final project workshop.

Suggested reading:

• jsPsych mouse-tracking extension documentation
• jsPsych eye-tracking overview
• jsPsych WebGazer extension documentation
• jsPsych-contrib repository and selected package documentation
• JATOS: jsPsych and JATOS
• Cognition.run documentation / platform overview

Core bibliography:

• de Leeuw, J. R., Gilbert, R. A., & Luchterhandt, B. (2023). jsPsych: Enabling an open-source collaborative ecosystem of behavioral experiments. Journal of Open Source Software, 8(85), 5351. https://joss.theoj.org/papers/10.21105/joss.05351
• de Leeuw, J. R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a Web browser. Behavior Research Methods, 47(1), 1-12. https://doi.org/10.3758/s13428-014-0458-y
• jsPsych documentation: https://www.jspsych.org/v8/
• jsPsych-contrib repository: https://github.com/jspsych/jspsych-contrib
• JATOS documentation: https://www.jatos.org/jsPsych-and-JATOS.html
• Cognition.run: https://www.cognition.run/

Assessment methods and criteria

1. Assessment methods

• Three short coding exercises / home assignments.
• Final project proposal and pilot submission.
• Final project: a small runnable online jsPsych experiment with brief technical and methodological documentation.

2. Components of the final grade and their weights

• Coding exercises: 30%
• Project proposal and pilot test: 10%
• Final project: 60%

3. Grading scale

• Below 50%: 2 (fail)
• 50% to below 60%: 3
• 60% to below 70%: 3+
• 70% to below 80%: 4
• 80% to below 90%: 4+
• 90-100%: 5

Apply these bands to the unrounded total; a score of 59.5% remains in the first passing band.

4. Requirements for retaking the assessment

• To be eligible for reassessment, the student must submit at least two of the three coding exercises and the project proposal by the original deadlines.
• Reassessment takes the form of revising and resubmitting the failed or incomplete coursework, especially the final project.
• A student who already obtained a positive final grade may improve it once by submitting a substantially revised final project within the retake period, provided all course requirements were originally submitted on time.

5. Exams in the exam session

6. Requirements for taking the exam

• Not applicable. The course is assessed through coursework and project work, not through an exam.

2. Possibility (and requirements) for retaking the exam in case of a positive grade

• Not applicable.

3. Early Exam Session (“Zerowka”)

• Not applicable.

Project assessment criteria:

• Technical correctness and completeness of the implementation.
• Alignment between the research question and the experimental design.
• Appropriate use of jsPsych features.
• Clarity of code organization and documentation.
• Evidence that the study was tested and prepared for online deployment.

Attendance rules

• Because the course is workshop-based, attendance is expected.
• One absence without consequences is permitted.
• A second absence is permitted only with a documented excuse and requires make-up work.
• Missing more than two classes may result in failure to obtain credit unless individually approved by the instructor for serious reasons.

Prerequisites

• No prior knowledge of JavaScript, HTML, or CSS is required.
• Students should already be comfortable with basic programming concepts such as variables, functions, loops, conditionals, and reading error messages, for example from prior work in Python or R.
• Students should be able to work with files and folders on their own computer and use a code editor.

Academic honesty

Students must respect the principles of academic integrity. Plagiarism, copying code or text without attribution, falsifying data, and submitting work that the student does not understand are serious violations.

AI policy:

• AI tools may be used for brainstorming, explaining documentation, debugging, and syntax support.
• Students remain fully responsible for all submitted code and text.
• Any substantial AI assistance must be disclosed in a short note attached to the assignment or project.
• Using AI to generate a complete solution that the student cannot explain or modify independently is not permitted.

Remarks

• Students should have access to a laptop and a modern desktop-class browser. Some advanced activities are not suitable for mobile devices.
• A webcam is not required. WebGazer is an optional instructor demonstration and methodological discussion; students may use the supplied observation worksheet.
• Community extensions discussed in the course may have version-compatibility constraints and may require adaptation before use in new projects.
• JATOS is the supported deployment exercise; Cognition.run is a documented alternative. The instructor supplies a suitable runner or arranges the local-pilot alternative described in the project brief. No paid account is required for the core coding work.

Workload and assessment alignment

The 2 ECTS design budgets approximately 55 hours: 15 hours of instruction, 5 hours of setup/readings, 9 hours for three coding assignments, 3 hours for proposal/pilot documentation, and 23 hours for the final project and revision. This is a planning estimate, not a time-based grading rule. Existing programme outcome codes above are carried forward from the supplied draft; the instructor should reconcile them with the programme’s approved syllabus before administrative submission.

Submission schedule and documents

The default relative schedule is usable without semester dates. Assignment 1 is due before Meeting 2; Assignment 2 before Meeting 3; Assignment 3 and the proposal before Meeting 4; the pilot before Meeting 5; the final project 14 days after Meeting 5 at 23:59 Europe/Warsaw. The instructor posts the corresponding calendar dates and upload links before Meeting 1. Extension and reassessment arrangements follow the existing course rules above and any binding programme rules.

See assessment for all briefs and scoring, the student guide for preparation, and the project brief for the complete deliverable. In-class pair work is encouraged; graded work is individual, with borrowed code and assistance acknowledged. A classroom pilot uses synthetic or voluntary classmate test inputs and makes no scientific inference about a population.