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

V2.09

Full Changelog: V2.06...V2.09

Improve GUI for editing variables, refactor for deployment

The variable editing panel has been improved, being able to live edit entries without removing them from the list. The possible entries are now dynamically generated depending on the selected stimulus.

Lots of underlying changes have been made to protocol loading and saving, and other changes to enable app deployment. Opticka can be fully deployed using the MATLAB compiler (only tested on macOS so far, but final target is Linux).

Full Changelog: V2.05...V2.06