Second semantic naming sweep-through about psychtaskframework

[shippy]

Other than "what things are named", there's also the problem of "where things are". For one:

• The config struct fields are confused. Why is s.default not under objects? Why are objects not elements? Should a lot of the setup be hidden under s.game, or should there now be s.task, s.blocks, s.phases and s.elements? (While we're at it, should data hide in s.blocks.recorded?)

[shippy]

This is non-exhaustive, but I have to get it out of my head and onto paper.

Proposed config structure:

• device - debug, screenId, windowPtr, screenDims, sleepIncrements, saveAfterBlock, saveAfterTrial, breakKeys, choiceKeys
• graphicDefaults (previously .default - font stuff, background color, between-objects padding
• task (previously game) - taskName, taskPath, imgPath?, conditions?, numSessions, numBlocks (/ blockLength?), constantTrialDuration, breakKeys, choiceKeys
• trials - runTrialFn, phases (cell array of PhaseConfig structs), phasesComplete?, RA phase functions (if re-using R&A stuff)?, levels & other generation logic
• objects -- arbitrary subfields for each drawn element, named such that the functions know where to look? Include even what functions to draw?
  • Remove antiquated text widths
  • Rename lottery.figure to lottery.box
  • Change stakes to payoffs? (would break compatibility with previously collected data files, unless accounted for everywhere data files are interfaced with)
• runSetup -- trials for the block, condition(s) used for the block? (Including repeatRow etc. here could reduce the complications in generateBlocks)
• subject -- any subject-specific info. Stuff like subjectId, refSide, etc.?
• custom -- any ad-hoc, user-defined spots

Proposed Data structure:

• observer -> subjectId
• numRecorded -> numFinishedBlocks
• Move planned, numRecorded, recorded into top-level struct fields
• .blocks.recorded{i}.records -> .recordedBlock{i}.trials
• blocks{i} [cell array pf blocks]
  • .config
  • .conditions
  • .trials (planned)
  • .data

This simplifies planned{i} and recorded{i}: trial info is duplicated between the two and config has little reason to change between then (except for multiple sessions, between which windowPtr and textures might change? might need to implement a "config refresh")

Other issues:

• Pre-fixing standard R&A objects to clear up the namespace? Out of scope for now.
• Should there be a different filename structure for condition configurations? Out of scope for now.
• objects vs. elements -- clear up terminology.
• Config is confusing -- looks like it's for the entire task, but then it's passed as blockSettings. Explain better.
• How to encode condition, or multiple conditions? See #93.
• Where does colorKey go? To the object for which it is necessary: s.objects.lottery.
• blockConfig is poorly defined. trialConfig is poorly defined. objectConfig is poorly defined.
  • blockConfig is now better-annotated, although passing it around is still a bit confusing.
  • trialConfig is the single-row table with columns sufficient to implement the trial phases.
  • objectConfig will remain unspecified for now, but should at some point get some standardized form.
• plurals in trialData (e.g. trialData.ambigs) are a convenience from generateBlocks -- get rid?
• config vs. settings? config might be more consistent.
• observer, participant -> subject

[shippy]

• debug (true)
• device
  • screenId
  • windowPtr
  • screenDims
  • rngAlgorithm
  • rngSeed
  • sleepIncrements
  • saveAfterBlock
  • saveAfterTrial
  • breakKeys
  • choiceKeys
• graphicDefaults
  • fontName
  • fontColor
  • fontSize
  • bgrColor
  • padding
• objects
  • ...
• task
  • taskName
  • taskPath
  • constantTrialDuration constantBlockDuration
  • numBlocks
  • blocksPerSession
  • blockLength
  • fnHandles
    • trialFn
    • preBlockFn
    • postBlockFn
    • bgrDrawFn
    • bgrDrawCallbackFn
    • referenceDrawFn
• trial
  • generate
    • ...
    • ITIs
    • catchTrial
    • catchIdx
  • phases (cell array -- invoked by runGenericTrial)
  • phases_RA legacyPhases (extracted from / refactored into a separate script?)
    • showChoice
      • phaseScript
      • action
      • duration
    • response
      • phaseScript
      • action
      • duration
    • feedback
      • phaseScript
      • action
      • duration
    • intertrial
      • phaseScript
      • action
      • duration
• runSetup
  • lookups
  • textures
  • trialsToRun (trial table, must be assigned by task master script for each block)
  • refSide
  • blockName / conditionName
  • blockKind / conditionKind conditions (#93)

[shippy]

fe0ba49 did the scary task of moving legacy settings away. What remains to be done, at least on the config side:

• runSetup
• Ensure that .game and .block are nuked from orbit
• Re-organize task & block/condition configs in order to make sense with the new system
• Go over the ITI assignment and figure out its standard path (basically, if set in phaseConfig, that overrules most anything, but should it?) Related to #87 and possibly movable into it. Moved to #87.

[shippy]

One possible solution to the "is config for the task, the block, or both?" is to start passing per-block settings to Data.plannedBlocks{i}.settings.

[shippy]

Implement the new structure of Data (and start using runNthBlock) for:

• RA
• MDM
• SODM
• UVRA
• HLFF

Implement the new conditions structure for:

• RA
• MDM
• SODM
• UVRA
• HLFF

[shippy]

To complete the Data restructuring, it will be necessary to do the following:

• change loadOrCreate to initialize the proper structure
• change exportSubject to look for the right fields

[shippy]

Since there's a lot of checklists up there, and they're a tad confusing, here's the tasks that remain to be done.

Summary of remaining tasks:

• re-organize task and block configs so that it's clear how they're used (see the pie-in-the-sky in #93)
• change loadOrCreate and exportSubject to work well with new Data structure
• settings -> config
• Look into removing the plurals in trialData (see: generateTrials / generateBlocks / config.trial.generate) Decided as not worth it
• objects -> elements draw
• stakes -> payoffs
• go over all files and look for un-semantic naming - redProb and blueProb from the OP are a good example
• move deprecated functions into lib/legacy

[shippy]

On reflection, I'm comfortable leaving in the plurals (can be changed on export if that's a problem) and stakes. Neither objects nor elements address the fact that the properties defined therein are for draw scripts.

I'm not sure what the solution here is. block > trial > phase > X nomenclature would imply that X should be a noun - but draw is a good description of what the scripts are for. (By comparison, "phase" is an artifice: it organizes or directs a particular scene, but neither of these words works very well.)

I'm leaning towards using "draw" more universally -- in this case, replacing objects with it. Will think about it en route to the Huettel talk.

[shippy]

In the light of #115, it might have been a good idea to rename Y1, Y2 and Y3 to lottoTop, lottoMiddle, lottoBottom and Y2occ, Y3occ to occluderTop, occluderBottom .