HED Tags on the march!

V2.18.1

Important

Major repository restructure — Core classes have been moved into subdirectories for better organisation. Please run addOptickaToPath again to update your MATLAB path. If you use custom scripts that reference files by their old paths, you may need to update those references. userFunctions have be refactored, you should make a child class that inherits userFunctions as its superclass (see DMTS protocol for an example of this).

New Features

• HED Tags Expanding — We are now adding HED tags to each state machine state and are generally adding more timestamped messages with HED tags to improve out metadata pipeline. See stateMachine.m and timeLogger.addMessage() functions. We updated to V8.4 of the HED standard and we always generate TSV files that are HED compatible when running behavioural tasks.
• AprilTag Stimulus (aprilTagStimulus) — New stimulus class generating binary checkerboard / AprilTag-style patterns directly from MATLAB pixel arrays rather than PNG textures. Supports user-defined pattern matrices or random generation, separate colours for 0/1 values, and crisp edge filtering (filter=0).
• Mentalab EEG Integration (mentalabManager) — New communication class sending strobes and triggers to Mentalab EEG recording systems directly from Opticka tasks.
• MinIO S3 Storage (minioManager) — New S3-compatible file transfer interface using the MinIO mc CLI tool (alias-based authentication). Supports cross-platform install via pixi global install minio-mc or direct download. Provides cp, ls, mv, sync wrappers with mc alias set. The previous awsManager is deprecated.
• Editable Combo Box UI (CompactEditableComboBox) — New custom App Designer UI widget combining text entry with dropdown list functionality. Entries persist across sessions, supports inline editing and new entry creation. Includes HTML renderer (compactEditableComboBox.html), event data class, and a demo script. Used in Opticka UI for saving and editing selection commands to send to Alyx database.
• DMTS Protocol — Delayed Match to Sample behavioural task: subject fixates, a sample image appears, after a delay a choice array of images appears at peripheral locations. Subject must saccade to the matching image. Full state machine + functions + protocol .mat file.
• VEP Test Protocol (VEPTest) — Visual Evoked Potential testing state machine with protocol file.
• Touch Saccade Tasks — Touch-screen versions of saccade/antisaccade (Saccade_AntiSaccade_touch) and double-step (Saccadic_DoubleStep_touch) tasks added to CoreProtocols/.
• alyxUploader (tools/alyxUploader.m) — Retroactive bulk upload tool for older ALF-format session data. Scans folder hierarchies, creates matching Alyx sessions with correct timestamps derived from filenames, and registers files with Alyx + S3/MinIO data repository.
• DataHash (data/DataHash.m) — New utility for computing cryptographic hashes of MATLAB data structures (534 lines).
• Image Stretching — imageStimulus now supports crop = 'stretch' to stretch images to fill the screen dimensions.
• Audio Ramp Duration — audioManager beeps now allow configurable rampDuration for onset/offset smoothing.
• userFunctions Integration — myUserFunctions.m as a child class template provides user-extensible methods accessible via uF.<method> in state machines.

Major Refactors

• Repository Restructure — Major project reorganisation: core classes moved to core/ (optickaCore.m, runExperiment.m, screenManager.m, stateMachine.m, taskSequence.m, runOpticka.m, DefaultStateInfo.m, userFunctions.m), data utilities to data/ (HEDTagger.m, HEDTags.m, behaviouralRecord.m, timeLogger.m, DataHash.m, getDensity.m, HED8.4.0_Tag.tsv), GUI classes to ui/ (opticka.m, opticka_ui.mlapp), and Omniplex/PLX reader to communication/omniplex/. addOptickaToPath updated accordingly.
• touchManager — Extensive refactor: support for multiple simultaneous touch windows, improved xinput device enabling logic, syncTime() method to reset touch event timing, updateWindow() for proper logging of touch window changes, enhanced touchData plotting with 3D scatter layout, dynamic figure naming, and improved axis labelling. Better handling of Type 1 touch events and device name validation (1034 lines changed).
• alyxManager — Comprehensive refactor: secure password handling via getSecret/setSecret with setSecrets() and getSecrets() methods; response caching using MATLAB dictionary for hasEntry() performance; transition to MinIO storage; QC PASS dataset support; improved login flow with automatic secret retrieval; better error handling and token refresh on 403 responses. Methods updated with arguments() blocks (1792 lines changed, major rewrite).
• timeLogger — Refactored to use arguments() blocks. New explicit HED property in addMessage() for HED tag annotations. Preallocation support for timing and message arrays. More robust empty-value removal and legacy format migration. Improved plot() and messageTable() with HED columns.
• screenManager — Major refactor with improved property validation, movie recording settings, compatibility updates (675 lines changed, moved to core/).
• stateMachine — Performance refactor (#11). Table view (showTable()) now more robust with UI figure support. Better logging and compatibility. (273 lines changed, moved to core/).
• optickaCore — Version updated to 2.18.1. New makeReport() method using MATLAB Report Generator toolbox for generating PDF/HTML reports of experiment parameters. getALF() updated with arguments() blocks. Improved clone() method for deep copies.

Eyetracking

• eyelinkAnalysis — Support for better saccade analysis toolbox integration (200 lines changed).
• tobiiAnalysis — Improved gaze point calculations with proper centering on display area. Enhanced plot() and plotMessages() functions showing the event log overlay (213 lines changed).
• Polar↔Cartesian — New static method for polar to cartesian coordinate conversion.
• Fixation Only protocol — Updated for compatibility.

HED Tagging

• Updated to HED schema V8.4 (new data/HED8.4.0_Tag.tsv, 1234 lines).
• HED tags now integrated into timeLogger.addMessage() for per-event HED annotations.
• stateMachine.m now includes a HED column so you can tag the states of your task.
• More comprehensive HED logging throughout runExperiment task flow.
• Old tools/HEDTags.m removed; replaced with data/HEDTags.m.

Improvements

• audioManager — Enhanced with volume control, beep vector caching for repeated sounds, getDeviceIndex() and showDevices() methods. Better device selection, silent mode handling, and error logging (231 lines changed).
• imageStimulus — Improved ignoreProperties, sizeOut calculation, file path handling, and image list clearing between trials.
• baseStimulus — Circular mask optimisation: no longer remakes the mask texture for every stimulus update (105 lines changed).
• menuN — Better font sizing on high DPI screens.
• joystickManager — Minor updates (2 lines).
• nirSmartManager — Minor improvements (4 lines).
• zmqConnection/jzmqConnection — HTTP proxy URL fix, minor refinements.
• makeReport — Refactored for better performance.
• analysisCore — Minor fixes (14 lines).
• PupillaryReflex — Minor protocol updates.
• Saccadic_DoubleStep — Protocol updates (12 lines).

Bug Fixes

• touchManager — Fixed xinput not enabling touch panel; better event handling for multiple touch windows; fixed device name validation; improved flush and event logging; fixed doNegation on last window only.
• audioManager — Fixed crash on initialisation; improved device assignment and silent mode logic; better sample state validation before playback.
• alyxManager — Fixed password property naming; hardened login error handling; improved re-sync logic; better connection failure handling.
• imageStimulus — Fixed updateXY() stimulus argument validation (V2.17.13); fixed image list clearing between trials (V2.17.7).
• screenManager — Fixed use of win not screen WhiteIndex on open().
• stateMachine — Fixed table view robustness.
• timeLogger — More robust handling of edge cases.
• Windows paths — Fixed compatibility issues.
• jzmqConnection — Fixed HTTP proxy URL.
• tobiiAnalysis — Fixed gaze point centering calculations.

Infrastructure

• AGENTS.md — New comprehensive agent instructions file consolidating project conventions, architecture, and documentation for AI coding tools.
• Copilot Instructions — New .github/copilot-instructions.md with developer guide.
• .gitignore — Updated with build directory and additional exclusions.
• addOptickaToPath.m — Updated for new directory structure (adds core/, data/, ui/ subdirectories).
• functionSignatures.json — Removed as properties validation is better.
• README.md — Minor updates (5 lines).
• Copyright — Updated to 2026 throughout.

Summary

198 files changed, 13,803 insertions(+), 2,736 deletions(-) — 88 commits by 2 contributors.

This major release focuses on repository restructuring, expanded behavioural task support (DMTS, VEP, touch tasks), new hardware integrations (Mentalab EEG, MinIO storage), comprehensive UI improvements (Editable Combo Box), and significant reliability enhancements across touch management, Alyx integration, and timing infrastructure.

V2.17.0

V2.17.0 Integration of ØMQ, CageLab and Alyx, and Titta Toolbox changes from Nierhorster et al., 2024

• Add support for ØMQ for communication messages (command + serialised MATLAB data packet) across networked PTB instances using the jzmqConnection class. This is much more robust than raw TCP/UDP used by pnet & dataConnection and we are using it for communication across CageLab devices. This adds a dependency on https://github.com/cogplatform/matlab-jzmq, a MATLAB wrapper for JeroMQ. The class explicitly supports a new neuroscience-targetted middleware called cogmoteGO with an API designed to manage multiple remote PTB instances and broadcasts behavioural data and results back to clients.
• Major update to the opticka UI for Alyx integration. There is an Alyx panel where you can connect to your Alyx instance to retrieve data from the server. Opticka can create a new Alyx session, and will upload the task data as a copy to the Alyx server. The data is sent to an AWS compatible data store linked to the Alyx session. The data is stored in a folder structure that matches the International Brain Lab ONE Protocol (see "A modular architecture for organizing, processing and sharing neurophysiology data," The International Brain Laboratory et al., 2023 Nat. Methods, DOI).
• Add awsManager to support AWS S3 storage. This is used to upload the task data to the AWS compatible data store linked to the Alyx session. This relies on the awscli command line tool to upload the data. You will need to install the AWS CLI and configure it with your AWS credentials. See AWS CLI for more information. We use the cross-platform pixi package manager to install AWS CLI, using pixi global install awscli to install it.
• HED Tagging -- we now support HED tagging of the session data. This is used to tag parameters with metadata that can be used for search / analysis. The tags are stored in a TSV file in the same folder as the raw session data. See tools/HEDTags.m and tools/HEDTagger.m. The HED tags are generated from the task sequence and the task parameters. We want to support better data sharing and Alyx / ONE protocol do not have any task metadata so we chose HED from the EEGLab / BIDS projects. See https://www.hedtags.org for details.
• runExperiment -- big improvements to the logging system. Previously task events were stored in several places, but for Alyx / HED we need to centralise the event data. This is used to generate the HED tags and the Alyx session data.
• Add joystickManager — we have built our own HID compatible joystick hardware and this manager interfaces with this hardware.
• labJackT — we now send an 11bit strobed word rather than 8bit word. In theory this is backwards compatible, but you need to update the Lua server code running on the LabJack to use the 11bit word (t = labJackT; t.initialiseServer). 0-2047 controls EIO0-8 & CIO0-3.
• Tobii eyetrackers — update Titta interface to support the new adaptive monkey calibration. See Niehorster, D. C., Whitham, W., Lake, B. R., Schapiro, S. J., Andolina, I. M., & Yorzinski, J. L. (2024). Enhancing eye tracking for nonhuman primates and other subjects unable to follow instructions: Adaptive calibration and validation of Tobii eye trackers with the Titta toolbox. Behavior Research Methods, 57(1), 0. https://doi.org/10.3758/s13428-024-02540-y for details.
• makeReport — a new method in optickaCore thus available to all opticka objects. Uses the MATLAB report generator to make a PDF report of the data and property values contained in the core opticka classes (runExperiment, taskSequence, stateMachine, behaviouralRecord, tobii/eyelink/irec). Useful when analysing an experiment to get an overview of all experiment parameters for that session.
• circularMask Shader — add a simple texture shader that provides a circular mask for any texture stimulus (like an image). This is better than using a separate disc shader as before (which blends with a background colour, not alpha). Used in imageStimulus and movieStimulus so you can alpha blend a masked image/movie against a complex background.

What's Changed

• V2.16.1 by @iandol in #5
• Update README.md by @iandol in #6
• Merge Dev by @iandol in #9

Full Changelog: V2.16.1...V2.17.0

V2.16.1 -- BIG Update

V2.16.1 -- 106 files changed

Tip

Please double-check changes in DefaultStateInfo.m to see the changes for state machine files, this may inform changes you could add to your own state machine files...

• BREAKING CHANGE: we want to support the International Brain Lab ONE Protocol (see "A modular architecture for organizing, processing and sharing neurophysiology data," The International Brain Laboratory et al., 2023 Nat. Methods, DOI), and we are now follwoing ALF filenaming for saved files. the root folder is still OptickaFiles/savedData/ but now we use a folder hierarchy: if the labName field is empty we use the shorter / subjectName / YYYY-MM-DD / SessionID-namedetails.mat otherwise we use / labName / subjects / subjectName / YYYY-MM-DD / SessionID-namedetails.mat -- the opticka MAT file will not change structure or content (it will remain backwards compatible), but we will add extra metadata files to help data sharing in future releases. We will add an ALYX API call to start a session in a future release.
• BREAKING CHANGE: LabJack T4 -- we increased the strobe word from 8 to 11 bits, now on EIO1:8 CIO1:3, this should in theory be backwards compatible as 8bits is still the same lines. Upgrade the LabJack T4 (connected over USB) like this:

t = labJackT();
open(t);
initialiseServer(t);
close(t);

• Add improved Rigid Body physics engine. We now use dyn4j, an open-source Java 2D physics engine. animationManager is upgraded (previously it used my own simple physics engine, which couldn't scale to many collisions). Opticka uses degrees, and we do a simple mapping of degrees > meters, so 1deg stimulus is a 1m object. A minimal use case to bounce a ball around the screen:

sM = screenManager();
b = imageStimulus('size',4,'filePath','moon.png',...
    'name','moon');
b.speed = 25; % will define velocity
b.angle = -45; % will define velocity
aM = animationManager(); % our new animation manager
sv = open(sM); % open PTB screen, sv is screen info
setup(b, sM); % initialise stimulus with PTB screen
addScreenBoundaries(aM, sv); % add floor, ceiling and
% walls to rigidbody world based on the screen dimensions sv
addBody(aM, b); % add stimulus as a rigidbody
setup(aM); % initialise the simulation.
for i = 1:60
	draw(b); % draw the stimulus
	flip(sM); % flip the screen
	step(aM); % step the simulation
end

• Improve touchManager to better use the rigid body animations with touch events. You can now finger-drag and "fling" physical objects around the screen.
• add Procedurally generated polar checkerboards: polarBoardStimulus, and improved polar gratings to mask with arc segments: polarGratingStimulus.
• added new stimulus: dotlineStimulus - a line made of dots.
• pupilCoreStimulus -- a calibration stimulus for pupil core eyetrackers.
• all stimuli: updateXY() method quickly updates the X and Y position without a full stimulus update(), used by the update animationManager.
• all stimuli: added szPx szD xfinalD and yFinalD properties so we have both pixels and degrees values available.
• all stimuli: szIsPx property tells us whether the dynamically generated size at each trial is in pixels or degrees.
• add nirSmartManager to support nirSmart FNIRS recording system.
• improved the mouse dummy mode for the touchscreen touchManager.
• arduinoManager can now use a raspberry pi GPIO if no arduino is present.
• Update image and movie stimuli to better handle mutliple images.
• Add a Test Hardware menu to opticka GUI. You can use this to test that the reward system / eyetracker / recording markers are working before you do any data collection each day.
• Updates to support the latest Titta toolbox for Tobii eyetrackers.
• optickaCore.geyKeys() -- support shift key.
• runExperiment -- better handling when no eyetracker is selected for a task that may have eyetracker functions.
• screenManager -- update movieRecording settings. You pass screenManager.movieSettings.record = true to enable screen recording. Note that the movie is handled automatically, so:

s = screenManager();
s.movieSettings.record = true;
s.open(); % this also initialises the video file
for i = 1:3
	s.drawText('Hello World);
	s.flip(); % this also adds the frame to the movie
end
s.close(); % this also closes the video file.

• lots of improvements for analysing Tobii and iRec data (see tobiiAnalysis and iRecAnalysis), in particular we integrate Nyström, M. & Holmqvist, K. 2010 toolbox to improve data cleaning.
• switch to using string arrays for comment property fields.

State Machine Changes:

• @()needFlip(me, false, 0); -- add a 3rd parameter to control the flip of the eyetracker window. NOTE: the number 0=no-flip, 1=dontclear+dontforce, 2=clear+dontforce, 3=clear+force, 4=clear+force first frame then switch to 1 -- dontclear=leave previous frame onscreen, useful to show eyetrack, dontforce=don't force flip, faster as flip for the tracker is throttled
• @()trackerTrialStart(eT, getTaskIndex(me)); & @()trackerTrialEnd(eT, tS.CORRECT) -- this is a new function that handles the several commands that were used previously to send the trial start/end info to the eyetracker. As we increase the number of supported eyetrackers, it is better to wrap this in a single function. NOTE: we mostly use the Eyelink message structure to define trials, even for other trackers, which simplifies analysis later on.

Tweaks and twiddles…

This is mostly a bunch of small tweaks and fixes. Some fixes to procedural checkerboard stimulus and some more logging fixes to improve performance for long tasks....

Auto What's Changed

• Dev branch by @iandol in #4
  Full Changelog: V2.15.12...V2.15.14

Tweaking State Machine Timing

I did a refactor of the state machine to ensure timing is accurate. This was prompted by doing lots of photodiode vs. strobe trigger tests. Opticka is super reliable but I noticed if we asked for 2 secs maintain fixation we actually have 2.036 secs stimulus. This is because the timer itself is managed by the eyetracker, but then the state machine must make the logic decision to transition to another state and this incurs a fixed two flips offset. If you absolutely need 2 secs you must use 1.964secs for a 60hz system. The state machine timers themselves are really precise (I tested to around 0.001ms).

• Added a UseVulkan switch to the GUI, as currently we have a bug with the display++ that is only fixed when using Vulkan.
• Add a polar grating (radial, circular and spiral) stimulus, with an arc segment mask option for fMRI etc.
• Add stereomode option to screenManager (only anaglyph stereo used so far).
• Improvements to the tobii / iRec / Pupil core operator display.
• Fix RFLocaliser that got broken when we added visibleRate.
• Improve visibleRate frequency accuracy.
• More Pupil Core bringup.

What's Changed

• Timingfixes by @iandol in #3

New Contributors

• @iandol made their first contribution in #3

Full Changelog: V2.15.11...V2.15.12

Refactor of Reward System

We currently support 3 different reward delivery systems: (1) standard variable-length TTL (2) custom-controlled peristaltic pump (3) fooed pellet dispenser. We added a reward structure to arduinoManager to set the parameters and type, then we can use the single command giveReward() to use the appropriate interface. Opticka GUI can now select among the options.

We also moved the eyetracker managers from communication to eyetracker folder, run addOptickaToPath to update the paths. We also add a pupilCoreManager to use the pupil core headset, we should be able to use our consistent API as for the eyelink / tobii / irec, some fixup is still needed for full functionality. But so far this eyetracker is very promising!!! You need to clone https://github.com/iandol/matlab-zmq and add the lib folder to the path; zmq support is precompiled for Linux and macOS.

For the iRec eyetracker, we can now screenshot the validation results pressing F1.

You can pass -1 to the audio interface in opticka GUI to disable the audio system, as we still face random crashes in Ubuntu 22.04

---

Full Changelog: V2.15.10...V2.15.11

Supporting the iRecHS2 Eyetracker

We have added a new eyetracker, the iRecHS2 (https://staff.aist.go.jp/k.matsuda/iRecHS2/index_e.html) which can use machine vision camera's from FLIR and works really well. For this we did a big refactor of the eyetracker so we use base classes eyetrackerCore and eyetrackerSmooth and inherit from them. As we first supported the eyelink, the tobii and iRec functions broadly mirror the eyelinkManager. It means you can use the same experiment code and any eyetracker should work unchanged. The iRec gains the Operator screen we use for the Tobii, so you can see fixation and eye data in real time as the experiment progresses.

Full Changelog: V2.15.3...V2.15.5

V2.13.2 -- bug fixes

This release fixes a few small GUI bugs, like not saving the subject name properly, and we've added a menu to change the Arduino board type (we support the classic Uno, but also Seeeduino Xiao and Raspbery Pi Pico).

Intan recording control

V2.13 adds the ability to send start / stop commands to the Intan. It also tweaked the GUI to split out the statemachine and userfunctions to separate tabs...

We also added some examples of using the imageStimulus to make "shapes" using alpha-masked images (see optickatest.m for an example).

NOTE: This version has reworked some of the runExperiment properties that may cause you to need to edit your stateInfo files to adjust to the new property names. Read through DefaultStateInfo.m to see what has changed...

Full Changelog: V2.11...V2.13.1

V2.11

The major changes are:

• Tobii gets a full-time monitor window to show the stimulus positions and eye plot summaries during the trial. The trackerDraw... functions used on the eyelink all work on the tobii so the same task code works to plot realtime eye data on either eyetracker.
• We've added a preliminary reverse correlation module. This is dense binary or trinary noise, with parameters modified via a separate dialog.
• The Help > Keyboard Mapping file now shows all keys for RFMapper module and the Tobii calibration key commands.
• Many small tweaks.

Full Changelog: V2.09...V2.11