PLDAPS 4.4.0

PLexon DAtapixx PSychtoolbox - Neurophysiology experiment toolbox for MATLAB

New developments with version 4.4.0

Tracking [ pds.tracking.trackObj.m, OOP ]

• On by default: p.trial.tracking.use = true;
• Eye/mouse/misc. tracking implemented with OOP object, located in [p.static.tracking]
• Calibration of raw signals performed on matlab-side allows for independent tracking of multiple sources (e.g. binocular eye) that can be set/recalled for multiple viewing distances. To run calibration, pause experiment, then execute the following from the command window:
  • pds.tracking.runCalibrationTrial(p)
• Calibrations are stored in user-specific & modality-specific calibration files automatically; most recent/appropriate calibration is automatically loaded during experiment startup.
• For usage, see new tutorial example: modularDemo.doRfPos_gabGrid

New tutorial for 'modular PLDAPS'

• Located in ./tutorials/modularDemo
• Execute from the command window with p = modularDemo.doRfPos_gabGrid()
• ...modular experimental design isn't itself new, but full fledged demo code is.
• More thorough README explanation to come...

Viewing distance flexibility with new pdsDisplay object

• OOP-based p.static.display object is automatically synced to the standard p.trial.display; No manual changes to experiment code are necessary to use
• OOP allows for automated communication between different experimental elements through event & listener triggers

---

A Wiki is coming!

An effort to develop [at least basic] documentation is being made in the Wiki

---

[glDraw] Branch

The glDraw branch is now the default PLDAPS branch, and also the only branch under active development. Continued use of the openreception branch is discouraged.

As new features are written & tested on the [czuba's] development fork, they will be transferred to stable release status here on the main HukLab PLDAPS project page.

=======

Version 4.3.0 (glDraw commit 354b233) brings additional low-level OpenGL drawing functionality, improved compatibility with various stereo drawing modes, and overall refinements.

Changes to Overlay drawing functionality...

The ability to draw elements to the overlay pointer once, then have them magically show up on both the overlay/experimenter display & the subject display is a cute feature, but it's time is coming to an end. Going forward, expect that things rendered to the Overlay pointer will only appear on the overlay window. Dealing with the ambiguity of 'which eye should the overlay render to during stereomodes?' is a major reason for this change. I can see of no current solution that doesn't require tedious piles of checks & drawBuffer changes that wouldn't outweigh their utility. In most all cases, the things being rendered this way are not so computationally intensive that there is a large benefit to only rendering them once in code, and the inherent limitations of indexd drawing (no alpha blending or smooth motion) make it unsuitable for many experimental stimulus applications anyway.

This may break/change functionality of some code (e.g. eyelink calibration targets), but fixes are being implemented as they come up. If you do come across an unfixed instance, feel free to contribute a solution. --czuba, 2018-05-11

---

Spring 2020 Note:

• minimal updates have been made to the text below to ensure the first few steps are at least 'not wrong'. Improved documentation is being made in the repo Wiki (...also slowly making its way over from the development branch)

...for now, on with the [outdated] readme!

---

Before we start

• PLDAPS is primarily developed/tested/supported on OSX (ver ~~10.10~~ 10.15) and Ubuntu (ver >= 16.04)
• Most modern Matlab versions should suffice; ~~>=2016b~~ 2019a is recommended
• Psychtoolbox needs to be installed
• If you are planning to use Datapixx, you should download a current version of the datapixx toolbox from vpixx.com and place it in the matlab path above[shadowing] the PTB copy. The datapixx code provided with PTB should be thought of as only a placeholder and is totally outdated.
• For a recording rig, all basic testing should be done (e.g. VBLSyncTest with and without datapixx, etc)

Getting started / installation

Create a local copy of PLDAPS by cloning the git repository ~~and select the version 4.2 branch (openreception)~~. In a terminal window, first go to the directory in which you want the PLDAPS directory to reside in.

    git clone https://github.com/HukLab/PLDAPS.git ~/MLtoolbox/PLDAPS

Now start Matlab and copy the function loadPLDAPS_template.m to a place in your path (e.g. your Matlab start folder), rename it to loadPLDAPS.m and edit the 'dirs' to include at least the path you just installed PLDAPS in. Now whenever you want to include PLDAPS in your path, just call loadPLDAPS

Framework:

pldaps

The core is a class called pldaps.

When a pldaps is created, it will load default parameters from different sources into a field called defaultParameters. This is again a class (named @params) that can handle a hierarchy of parameters. Importantly, pldaps is a handle class.

Quick aside on handle classes We use a handle class for pldaps because it allows a reduction of some memory allocation, which translates to increased speed during the trial. There are a couple of downsides to using handle classes (for one, it appears that storing function handles in a handle class reduces the performance.), but this appears to be the fastest easy way to be able to add data to a struct from inside a subfunction. It might be possible to go via a mex file to get real pointer behavior without the downsides of a handle class

Specifically, assume you have an object p of type pldaps

    p=pldaps;

Any changes made to a copy of p, will also effect p, as they are in fact using the same memory.

    p2=p;
    p2.defaultParameters.newParameter='I told you so';
    display(p.defaultParameters.newParameter);

notice that I created a new Parameter newParameter in object p2, but but now you can also access it using p, because p2 und p are identical.

Creating a pldaps class:

Typical use of the pldaps contructor includes the following inputs*: 1. Experiment setup function 2. Subject identifier 3. Settings struct containing hierarchies for additional experiment components (e.g. ) and/or changes to defaultParameters (e.g. to add/change values from your 'rigPrefs' to be applied only on this particular run)

The order of inputs is somewhat flexible**, but the only officially supported order is as follows:

	p = pldaps( @fxnsetupFunction, 'subject', settingsStruct )

• setupFunction must be a function handle (i.e. @fxn ) to your setup function

  • ...using a function handle here allows tab completion, which is nice

• subject must be a string input.

• settingsStruct must be a structure.

  • Defining core modules/components of your experiment (i.e. hardware elements, stimulus parameters, etc...see demo code for examples)
  • Fieldnames matching fields already present in defaultParameters [& within their respective param struct hierarchies] will take on the value in settingsStruct.
    • e.g. toggle the overlay state for this run by creating settingsStruct.display.useOverlay = 1. Note: you need not build every field of the .display struct into this; fieldnames will be matched/updated piecewise

• condsCell, a fourth input of a cell struct of parameters for each trial can also be accepted. Use of this input is relatively depreciated and should only really be used for debugging purposes. Trial specific parameters are better dealt with inside your setupFunction (when setting up p.conditions{}).

(* all inputs are technically optional, but PLDAPS won't do much without them.) (** In most—but not all—cases PLDAPS will still be able to parse disordered inputs, but lets not leave things to chance when we don't have to.)

Running pldaps

p now exists as a PLDAPS class in the workspace, but the experiment hasn't started yet, and the provided experiment function has not been called yet.

Execute the .run method to actually begin the experiment:

p.run

pldaps.run

pldaps.run will open the PTB screen and interface with a number of external hardware devices and will call a function each trial.

pldaps.run opens a Psychtoolbox window using p.openScreen

once the Psychtoolbox screen is created pldaps.run will call the experiment function provided in the constructor call (@functionname described above). This function

• can define the functions being called each trial (later),
• define any further colors you want to use in a datapixx dual clut scenario
• create anything that should be created before the first trial starts,
• define any stimulus parameters that are true for all trials in p.defaultParameters
• and should add a cell of structs to p.conditions that that holds the changes in parameters from therse defaults for each_trial

note: in later versions, p.conditions might actually only hold information about certain conditions and another field the info of what conditions to use in each trial.

note: since the screen is already created, basic screen parameters like the backgound color must be defined before the p.run is called.

pldaps.runTrial

unless another function is specified in the parameters as the p.defaultParameters.pldaps.trialMasterFunction it defaults to dv.defaultParameters.pldaps.trialMasterFunction="runTrial";

This is a generic trial function that takes care of the correct course of a trial. It will run through different stages for the trial and in a loop for each frame run through stages from frameUp