Standard library reference¶

Main library methods¶

These functions provide functionality at the highest levels of abstraction.

PTF.lib.configDefaults(changes)¶

Default documented config for all tasks in a freely modifiable struct.

Colors, when given, are RGB colors. PTB also accepts RGBA and CLUT.

The defaults used here err on the side of catering to LevyLab's R&A paradigm. If you're not using it, nuke s.draw from high orbit.

Although the resulting structure contains task-wide config, it is typically modified with block-specific config right before being passed to runBlock or equivalent. For example, RA_blockDefaults(configDefaults) would modify these defaults to serve all RA block kinds. RA_lossConfig would then modify the result of that call for loss-domain blocks, like so:

config = RA_blockDefaults(configDefaults); lossConfig = RA_lossConfig(config);

Most often, XYZ_blockDefaults will use configDefaults as a starting point without an argument. That is a useful option if you don't expect making any modifications to configDefaults for all your tasks.

Parameters:	changes -- A field of modifications made to the original set-up (not implemented)

Note

changes is not actually implemented yet. Instead, directly modify the structure returned by the function.

Returns:	The default config struct with all standard task settings
Return type:	struct

Todo

Implement changes to bring some order to post-return alterations.

PTF.lib.runBlock(Data, blockConfig)¶

Scaffolds multiple trial calls of the same kind. Saves results to file.

Deprecated in favor of runNthBlock.

The main thing runBlock needs from blockConfig is for .task.fnHandles.trialFn to be a function handle to which it can pass Data, trial #, and blockConfig.

If blockConfig.game includes fields preBlockFn and/or postBlockFn, it will assume they are callable functions and call them with Data and blockConfig as arguments. (This means they can display block beginning / end and wait for keypress, or check if requisite values exist and fail gracefully, or any number of other things.)

If Data.filename does not exist, it will not know how to save the trial choices (and will issue a warning).

Parameters:	Data -- Information collected from task trials blockConfig -- The block settings
Returns:	Information collected from task trials.
Return type:	DataObject struct

PTF.lib.runGenericTrial(trialData, blockConfig)¶

Runs through all the phases of an arbitrarily defined trial.

Fully generalized workhorse function to display any phases of an individual trial, as defined using PhaseConfig objects in blockConfig.trial.phases.

Parameters:	trialData -- Table of properties of the trial about to be run blockConfig -- The block settings
Returns:	Table of trial properties + information gathered from a trial.
Return type:	trialData

PTF.lib.runNthBlock(Data, n)¶

Runs a specified block and saves that block to a specific location.

Runs Data.blocks{n}.trials using Data.blocks{n}.config and saves the collected results to Data.blocks{n}.data. See lib/configDefaults.m for the parameters that a block can have.

If Data.filename does not exist, it will not know how to save the trial choices (and will issue a warning).

(Replaces runBlock, which is now deprecated.)

Parameters:	Data -- Information collected from task trials n -- An integer index of the block to run in Data.blocks{n}
Returns:	Updated information collected from task trials.
Return type:	Data

PTF.lib.runPhase(trialData, blockConfig, phaseConfig)¶

Run a generic phase defined with a phaseConfig construct.

Parameters:	trialData -- Table of trial properties blockConfig -- The block settings phaseConfig -- The phase settings
Returns:	Table of trial properties, updated with collected data
Return type:	trialData

PTF.lib.runRATrial(trialData, blockConfig)¶

Workhorse function to display all typical phases of an risk-and-ambiguity trial.

Deprecated in favor of runGenericTrial.

In turn, it displays the task-specific choice options, response prompt, response input feedback, and the intertrial period. It displays them using function handles set in blockConfig.trial.legacyPhases.

Parameters:	trialData -- Table of trial properties blockConfig -- The block settings
Returns:	Table of trial properties, updated with collected data
Return type:	trialData

Phase methods¶

PTF.lib.phase.legacyPhaseStruct()¶

Default phase config for R&A-based tasks. Deprecated.

If you're only changing some element of a phase, but you're happy with the standard order of phases (i.e. choice display, response prompt, feedback, intertrial), you can substitute a function here. It should take, and return, the same arguments that the phase function in lib/phase does. (In general, this is sampleFn(trialData, blockConfig, phaseConfig).)

By design, showChoicePhaseFn is left blank. runRATrial will complain if it is not set, or if any of the phase function handles below are unset. While you might avoid setting it by writing your own trial script, it is recommended that you still leverage these config; it will make your task easier to maintain and understand for your collaborators.

By design, s.game.responsePhaseFn is set to @phase_response; however, if your showChoice function collects responses during the display, it can be set to NaN.

Returns:	The phase settings for risk and ambiguity tasks.
Return type:	phases_RA

PTF.lib.phase.phaseConfig(name, varargin)¶

Prepares a uniform structure for the definition of a phase.

Parameters:	name -- The phase name or ID 'PropertyValue1', ... ('PropertyName1',) -- Any number of phase configuration properties
Returns:	The phase settings.
Return type:	phaseConfig

PTF.lib.phase.phase_ITI(trialData, blockConfig, phaseConfig)¶

Displays the intertrial "refocus" symbol in between trials.

Display duration is based on the value in trialData.ITIs.

Parameters:	trialData -- The participant data from a trial blockConfig -- The block settings phaseConfig -- The phase settings
Returns:	The participant data from a trial.
Return type:	trialData

Todo

Modular phase has no smart way of determining what the duration should be if it is constant. It relies on a duration fields in blockConfig.trial.legacyPhases.{X} enumeration. Possible solution: trialData.trialDuration, which checks for blockConfig.task.constantBlockDuration to see what duration to do. (Alternative: if isnan(phaseConfig.duration), need to compute it.)

PTF.lib.phase.phase_feedback(trialData, blockConfig, phaseConfig)¶

Displays feedback of trial choice for a specified time.

Based on the value in trialData.choice, draws the feedback that confirms to the player which option they chose (or whether they chose at all) and displays it for blockConfig.trial.legacyPhases.feedback.duration. Can be re-used for tasks that offer two options in a choice.

Parameters:	trialData -- The participant data from a trial blockConfig -- The block settings phaseConfig -- The phase settings
Returns:	Updated participant data from a trial.
Return type:	trialData

PTF.lib.phase.phase_generic(trialData, blockConfig, phaseConfig)¶

Run a "run-of-the-mill" phase

Parameters:	trialData -- The participant data from a trial. blockConfig -- The block settings phaseConfig -- The phase settings
Returns:	The (possibly updated) participant data from a trial.
Return type:	trialData

PTF.lib.phase.phase_response(trialData, blockConfig, phaseConfig)¶

Draw response prompt and handle potential response keypress or lack thereof.

Takes standard phase script arguments.

Parameters:	trialData -- The participant data from a trial blockConfig -- The block settings phaseConfig -- The phase settings
Returns:	Updated participant data from a trial.
Return type:	trialData

PTF.lib.phase.phase_showChoice(trialData, blockConfig, phaseConfig)¶

Phase shows the choices defined in trialData and blockConfig.

This includes a lottery and a reference. If available, executes action defined in phaseConfig.action; otherwise, waits for duration.

Parameters:	trialData -- The participant data from a trial. blockConfig -- The block settings phaseConfig -- The phase settings
Returns:	Updated participant data from a trial.
Return type:	trialData

PTF.lib.phase.pickAndEvaluateTrial(DataObject, config)¶

Picks a recorded trial at random, evaluates it, and displays the outcome.

This can be run as a post-block callback. To do this, include blockConfig.task.fnHandles.postBlockFn = @pickAndEvaluateTrial in your configuration file.

Parameters:

DataObject -- An object with participant records & other session info
config -- A standard block setting (from trial to block to Screen)

Returns:

2-element tuple containing

outcomeKind: Type of outcome picked (reference, win, or loss)
outcomeLevel: Type of choice picked (reference or lottery)

Warning

This was written in a hurry, and should at some point be refactored.

PTF.lib.phase.preBlock(Data, blockConfig)¶

Display "Block N: (BLOCKNAME)" and wait indefinitely for a break key.

Break keys are defined in blockConfig.device.breakKeys.

Parameters:	Data -- Information collected (in this case on blocks) blockConfig -- The block settings
Returns:	Information collected (unchanged) blockConfig: The block settings (unchanged)
Return type:	Data

PTF.lib.phase.helpers.choiceReport(trialData)¶

Prints to stdout participant choice and decision properties.

Parameters:	trialData -- A table of trial information
Returns:	Whether participant chose the lottery and what the properties of the offered lottery were.
Return type:	boolean

PTF.lib.phase.helpers.findPTBTimestamp(trialData, phaseConfig)¶

Return the correct timestamp from the (optional) structures, or getSecs() if nothing suitable is found.

Suitable locations:

startTimestamp field in phaseConfig
${PHASENAME}Start or ${PHASENAME}StartTS in trialData.

Parameters:

trialData -- A table of trial information
phaseConfig -- Phase configuration

Returns:

2-element tuple containing

PTBTimestamp: A record of the PTB trial timestamp.
found: A boolean signaling whether a timestamp was found. If false, the returned PTBTimestamp is the output of GetSecs().

Draw methods¶

PTF.lib.draw.drawBgr(blockConfig, callback)¶

Draws default background and sets default drawing properties

The most important default drawing properties set are fontName and fontSize.

To draw task-specific things, you can supply a callback function that does them. For instance, you can supply the task-relevant drawRef function.

Parameters:	blockConfig -- The block settings callback -- A function handle to execute after the function has concluded.
Returns:	Like all draw functions, it has no return.

Note

Unlike other draw functions, drawBgr only takes blockConfig, not trialData, and does not allow access to or modification of trialData.

PTF.lib.draw.drawFeedback(trialData, blockConfig)¶

Draws the feedback according to trial data and config.

Parameters:	trialData -- The participant data from a trial blockConfig -- The block settings
Returns:	Like all draw functions, it has no return.

Todo

If blockConfig.draw.lottery.verticalLayout is set to true, the feedback should be be drawn to the side vertically rather than horizontally.

PTF.lib.draw.drawITI(trialData, blockConfig)¶

Draws the inactivity symbol (by default, white oval) between trials.

Parameters:	trialData -- The participant data from a trial (unused) blockConfig -- The block settings
Returns:	Like all draw functions, it has no return.

Todo

Nigh-duplicate code with drawResponsePrompt. Factor out the general "draw an object in the center when provided the center and blockConfig.draw.(object)".

PTF.lib.draw.drawLotto(trialData, blockConfig)¶

Draws a lottery as specified in trialData in the center of the screen.

Uses an open PTB screen and other properties of blockConfig. If blockConfig.draw.lottery.offCenterByPx exists, drawLotto will shift the lottery by the specified amount of pixels.

Note

If you wish to draw multiple lotteries or determine the offset dynamically, you will need to hot-patch the arguments to this function. A redress is under development.

Parameters:	trialData -- Trial properties and collected participant data blockConfig -- The block settings
Returns:	Like all draw functions, it has no return.

PTF.lib.draw.drawRef(blockConfig, trialData)¶

Draws the stable reference value on screen.

To get the side and reference value, it uses getReferenceSideAndValue, which searches the structures supplied as arguments.

If blockConfig.draw.lottery.verticalLayout is set to true, the reference will be drawn to the side vertically rather than horizontally.

Parameters:	blockConfig -- The block settings trialData -- Trial properties and collected participant data
Returns:	Like all draw functions, it has no return.

PTF.lib.draw.drawResponsePrompt(trialData, blockConfig)¶

Draws the response prompt symbol (by default, green oval).

Parameters:	trialData -- Trial properties and collected participant data blockConfig -- The block settings
Returns:	Like all draw functions, it has no return.

Todo

Nigh-duplicate code with drawITI. Factor out the general "draw an object in the center when provided the center and blockConfig.draw.(object)".

PTF.lib.draw.helpers.centerRectDims(center, rectSize, pxOffCenter)¶

Finds center of screen and centers objects.

A helper function to calculate what the top-left pixel of an object is such that the object will appear centered. Accepts center that defines [x y] of the screen's center, rectSize that defines the object's dimensions, and (non-obligatory) pxOffCenter, which shifts the resulting position.

If pxOffCenter is supplied, shifts the computation by that much in both dimensions.

Parameters:	center -- The 2x1 coordinates of (a screen's) center rectSize -- The 2x1 dimensions of a rectangle (screen) pxOffCenter -- A simple integer value by which the result should be adjusted in both dimensions.
Returns:	The 2x2 rectangular matrix of xy-coordinates usable as argument for PTB::Screen functions.

PTF.lib.draw.helpers.dollarFormatter(value, windowPtr, fontSize)¶

When given a numerical value, outputs its correct format in dollars and, if provided windowPtr, its width and height on screen.

If fontSize is not provided, the width and height will be estimated with currently set font size.

Parameters:

value -- Any integer to be conveted into a dollar string
windowPtr -- A window pointer to specify active screen
fontSize -- The desired font size of the displayed dollar amount

Returns:

2-element tuple containing

txt: A string of monetary values.
dims: The dimensions of txt when printed

PTF.lib.draw.helpers.getTextDims(windowPtr, txt, fontSize)¶

For window at windowPtr, get dimensions of txt.

This will be at current font size or, if provided, at fontSize.

Adapted from Ruonan Jia's initial implementation in the MDM task.

Parameters:	windowPtr -- A window pointer to specify active screen txt -- The characters displayed on a screen fontSize -- The size of the existing text
Returns:	The 1x2 dimensions of the displayed text.

PTF.lib.draw.helpers.imgLookup(keyIdx, fnameLookupTbl, textureLookupTbl)¶

Supplies the texture and image dimensions of an image.

Looks up what texture keyIdx corresponds to, taking it for a simple index in fnameLookupTbl. (The middle step is looking up what texture ID a picture identified by its path corresponds to.)

Assumes a fnameLookupTbl has a list of image filenames. If textureLookupTbl is provided, it is assumed it was created by loadTexturesFromConfig and is up-to-date. If not, an error is thrown, as imgLookup does not have a pointer to the currently open Screen it would need to create the texture on its own.

Parameters:

keyIdx -- A key index
fnameLookupTbl -- A table composed of image filenames to draw from
textureLookupTbl -- A table composed of image textures

Returns:

2-element tuple containing

textureId: An image specific texture ID
imgDims: The specific image dimensions

Warning

There is no enforcement of image paths being supplied as absolute paths.

PTF.lib.draw.helpers.orderLotto(trialData)¶

Set up the probability and win/loss amount for each lottery.

Given the win color for the trial, it returns two sorted matrices with the probability (and, respectively, payoff) values sorted such that the first will appear on top and the second on the bottom of the drawLotto display.

Parameters:	trialData -- The data stored for each trial
Returns:	2-element tuple containing probOrder: A probability matrix of a win versus a loss. amtOrder: A matrix of the amount that was won or lost.

PTF.lib.draw.helpers.textLookup(keyIdx, lookupTable, windowPtr)¶

Looks up a text by key, optionally computing text dimensions.

Given an index in keyIdx, returns the (presumed character array) value corresponding to that index in lookupTable cell array. If provided windowPtr, also returns the dimensions that the text would take up under the current config in that PTB window.

Parameters:

keyIdx -- A key index
lookupTable -- A table containing indexed values
windownPtr -- A window pointer to specify screen

Returns:

2-element tuple containing

txt: The characters displayed on a screen.
txtDims: The dimensions of the displayed text.

PTF.lib.draw.helpers.xyAndDimsToRect(xy, dims)¶

Given origin point and dimensions, returns the rect matrix for Screen.

Converts a top-left xy-coordinate and a 2x1 widthxlength matrix to 2x2 dimensions expected by PsychToolBox's Screen.

Parameters:	xy -- The coordinate top-left origin of an object dims -- The dimensions (height and width) of an object
Returns:	A rectangle usable by Screen
Return type:	rect

Action methods¶

PTF.lib.action.action_collectResponse(trialData, blockConfig, phaseConfig)¶

Phase action to record the participant's response.

For duration specified in phaseConfig.duration, waits for one of the keypresses specified in blockConfig.device.choiceKeys.

Warning

Currently, the function is R&A-specific: it will only expect the first two keys, and it will recode the choice to choseLottery via keyToChoice.

Parameters:	trialData -- The participant data from a trial so far blockConfig -- The block settings phaseConfig -- The phase settings
Returns:	Updated participant data from a trial.
Return type:	trialData

PTF.lib.action.action_display(trialData, blockConfig, phaseConfig)¶

Phase action to simply display phase content without any interaction.

Duration is specified in phaseConfig.duration.

Parameters:	trialData -- The participant data from a trial so far blockConfig -- The block settings phaseConfig -- The phase settings
Returns:	Updated participant data from a trial.
Return type:	trialData

PTF.lib.action.action_waitForBreak(trialData, blockConfig, phaseConfig)¶

Phase action to wait for a break key press.

For a duration specified in phaseConfig.duration, waits for the press of a break key defined in blockConfig.device.breakKeys.

Parameters:	trialData -- The participant data from a trial so far blockConfig -- The block settings phaseConfig -- The phase settings
Returns:	Updated participant data from a trial.
Return type:	trialData

Setup methods¶

Setup functions prepare the task to be displayed, be it through generating its varieties or through establishing the necessary PsychToolbox infrastructure.

PTF.lib.setup.addGeneratedBlock(DataObject, blockTrials, config, conditions)¶

Properly stores ordered block components (trials and config) in a DataObject.

Parameters:	DataObject -- An object storing block components blockTrials -- A table of trials set up for each block config -- A configuration of the block components conditions -- A structure of how to configure block components
Returns:	An object storing block components.
Return type:	DataObject

PTF.lib.setup.generateBlocks(blockConfig, catchTrial, catchIdx, adHocTrials)¶

Returns a cell array of trial tables within a block.

Trial tables are generated with generateTrials from blockConfig.trial.generate, separated into blocks with a fixed number of rows (defined in blockConfig.task.blockLength). If given further arguments, it will also add to the final trial table the table catchTrial at per-block indices passed in catchIdx. If adHocTrials are provided, they are mixed in with the generated trials prior to randomizationand separation into blocks.

Note

catchTrial must include all the columns that generateTrials will create based on blockConfig.trial.generate. An easy way to find what these are is to run this function without catchTrial or catchIdx.

If catchIdx is not provided, the catch trial will be placed randomly within each block.

The function also adds ITIs to be generated per trial.

Note

If ITIs matter (e.g. for fMRI tasks), make sure that you've provided as many of them as necessary for non-catch trials. (Catch trials must have their own ITI defined in the column ITIs.)

Parameters:	blockConfig -- A configuration of the block catchTrial -- An single-row table with trial properties for a catch trial catchIdx -- (Optional) Catch trial is to be presented as catchIdx'th trial adHocTrials -- Any added trials to block
Returns:	An array of trial tables in block.
Return type:	plannedBlocks

PTF.lib.setup.generateTrials(levelConfig)¶

Generates a table of risk&ambiguity trials that contain all: combinations of levelConfig struct subfields.

Parameters:	levelConfig -- A configuration level containing trial information
Returns:	A table of all the trial information to be collected.
Return type:	trialTbl

Note

The generator is specific to the risk/ambiguity task. It expects that the struct will contain stakes and at least one of (probs, ambigs) fields. It will also combine them in a particular way (specifically, assuming that all ambiguous trials are coupled with .5 probability, and all probability trials have at least one appearance with zero ambiguity). It distributes all other subfields it finds randomly across thus generated trials.

Note

If you wish to omit any ambiguous trials but do not wish to delete the struct field, you can also pass an empty matrix to achieve the same result.

There is currently no way to disabuse generateTrials of the assumption that the midpoint of ambiguity occluder is at 0.5.

Generally speaking: if your task only differs slightly from the monetary R&A task, you should be able to use this script with minimum alteration. If your task is substantially different, you might have to roll your own.

PTF.lib.setup.importTrials(filename)¶

Create a table of trial properties by reading them from a tabular file.

If the provided does not exist, it will raise an error.

Warning

The function does not verify that the file defines the _correct_ properties; indeed, it just reads the file and returns its contents.

Parameters:	filename -- File name of a tabular file (e.g. in CSV format) with trial properties
Returns:	A table of the trial information.
Return type:	trialTable

Todo

Maybe this does not have to be a hard failure, but rather could allow a graceful fallback onto on-the-fly generation?

PTF.lib.setup.loadPTB(config)¶

Start PsychToolBox; return config struct with display info.

Most importantly, the display info is in config.device; the essential one is s.device.windowPtr.

Parameters:	config -- Initial configuration of a PTB set-up
Returns:	Updated configuration of PTB set-up
Return type:	config

PTF.lib.setup.loadTexturesFromConfig(configStruct, textureMap)¶

Create a texture map of images and image information.

Given a configStruct, it will extract file paths named .img and return a container mapping valid image filenames to a struct containing PTB's .textureId and their dimensions in .dims. If provided with a previously generated textureMap, it will avoid redundant loading of previously loaded images.

Parameters:

configStruct -- A configuration structure containing named images
textureMap -- Optionally, a previously created textureMap to update

Returns:

A data structure of texture pointer and dimensions mapped to a: filename.

Return type:

textureMap

PTF.lib.setup.preparePractice(DataObject, selectBlockIdx, numTrialsFromBlock)¶

Trims DataObject.blocks to selected indices; selects numTrialsFromBlock at random.

Parameters:	DataObject -- An object containing data on blocks selectBlockIdx -- An array of selected block indices numTrialsFromBlock -- The number of trials within a given block
Returns:	An updated object containing data on (trimmed) blocks
Return type:	DataObject

PTF.lib.setup.setupPracticeConfig(config)¶

Disable saving and randomize reference side assignment for practice runs

Parameters:	config -- A configuration of practice runs
Returns:	An updated configuration of practice runs
Return type:	config

PTF.lib.setup.unloadPTB(varargin)¶

Closes windows & textures from the passed config(s). Resets Screen config.

closeScreen accepts arbitrarily many config structs.

Parameters:	config2, ... (config1,) -- Any number of configuration objects

Export methods¶

PTF.lib.export.exportSubject(DataObject, fname)¶

Given a DataObject, it unites all records in one table.

If given fname, it will also write the table into a file.

The file format has to be any that writetable can handle; consult its docs.

Parameters:	DataObject -- An object containing participant data. fname -- Optionally, a file name to save the resultant table in.
Returns:	A table containing all recorded information in all blocks.
Return type:	exportTable

PTF.lib.export.exportTaskData(taskName, fname)¶

Exports all subject data in tasks/taskName/data.

Note

The function merely concatenates the sequential outputs of exportSubject.

Parameters:	taskName -- Name of the task to export. Assumed to be folder name. fname -- Optional file name in which to save the results table.
Returns:	A table of all participant data collected in the task.
Return type:	exportTable

Various helper methods¶

PTF.lib.helpers.configHasLookups(config)¶

Checks if lookups exist and are non-empty. (Tests presence of image payoffs.)

The function is commonly used to detect if the config defines an image + text value to substitute for the value in trialData specification.

Parameters:	config -- Block configuration
Returns:	Boolean true if lookups field is present and contains content.
Return type:	bool

PTF.lib.helpers.cutArrayToSize(arr, n)¶

Cuts, or extends, arr so that it has length n.

If n is not a direct multiple of the length of arr, the first n %% length(arr) elements are used.

Parameters:	arr -- A cell array n -- Length of desired array
Returns:	A cell array with desired length
Return type:	arr

Todo

If this is a character array, make it into a cell array to ensure expected behavior.

PTF.lib.helpers.experimentSummary(Data, blockId, trialId, bagMap)¶

Picks a trial; returns info necessary for in-person lottery realization.

Warning

Deprecated. Use methods that evaluate lotteries instead.

If bagMap is supplied, it will use it instead of the default lookup map.

You might want to load the bagMap via readtable from a CSV/XLS file.

Note

This is different from the original behavior of experimentSummary, which returned a human-readable struct array that encompassed all trials.

PTF.lib.helpers.getBlocksForPractice(practiceBlocks)¶

Give the practice blocks to run from a trimmed practice-only block set.

Warning

Deprecated. Use methods that evaluate lotteries instead.

Note

Assumes that preparePractice has been run, removed the blocks that weren't selected, and re-numbered the block span.

Parameters:	practiceBlocks -- A set of practice blocks
Returns:	2-element tuple containing firstBlockIdx: The index of the first block to run lastBlockIdx: The index of the last block to run

PTF.lib.helpers.getBlocksForSession(DataObject, blocksPerSession)¶

Find the indices for the blocks to begin and end the current session.

Parameters:

DataObject -- An object containing block information
blocksPerSession -- The number of blocks to run this session

Returns:

2-element tuple containing

firstIdx: The index of the first block.
lastIdx: The index of the last block.

Note

If all blocks have been done already, lastIdx will be an empty vector. This will prevent any loop of the form k:lastIdx from running, but you should make sure you don't rely on the numericity of lastIdx in other ways.

PTF.lib.helpers.getReferenceSideAndValue(trialData, blockConfig)¶

Extracts properties of the reference from both supplied configuration structs.

Checks if there is any specific reference side & value defined for this trial, or for this block. If reference side is unavailable, generate it at random.

Parameters:

trialData -- A table of trial information
blockConfig -- A block configuration

Returns:

2-element tuple containing

referenceSide: Side on which the reference should be displayed
referenceValue: The value to display.

PTF.lib.helpers.isFunction(x)¶

Is the argument a function handle?

Parameters:	x -- Any matlab object
Returns:	A boolean to determine if x is of class function handle
Return type:	bool

PTF.lib.helpers.isFunctionOrFunctionArray(x)¶

Is the input object is a function handle or a function handle array?

Parameters:	x -- Any matlab object
Returns:	true if x is function handle or a cell array full of function handles.
Return type:	bool

PTF.lib.helpers.loadOrCreate(subjectId, fname)¶

Load a subject data file. If it does not exist, create it.

Parameters:

subjectID -- A participant ID
fname -- A filename

Returns:

2-element tuple containing

Data: Participant information.
existed: Boolean reporting whether the file previously existed, or

had to be created.

Warning

Currently assumes that subject data is stored in a struct called Data, and that the folders in the path to fname all exist.

PTF.lib.helpers.prependPath(filenames, path)¶

When given a cell array filenames, returns that cell array with path added before each element of the cell array.

Parameters:	filenames -- A cell array of file names path -- A string folder on which the filenames are located.
Returns:	A cell array with 'path' before each array element.
Return type:	fullpaths

PTF.lib.helpers.saveData(Data)¶

Saves a subject data file to Data.filename.

Ensures that it stores the struct Data correctly, such that loadOrCreate can load it properly.

Parameters:	Data -- Participant information.
Returns:	Participant information.
Return type:	Data

Warning

The function assumes that the trial-handling functions haven't overwritten previous records in Data, and as such, overwrites the file without warning.

Todo

Determine what a file that's being overwritten with different info would look like, and test for that