Separate out trial generation from generateBlocks

[shippy]

This violates single responsibility principle, makes the code hard to read, and makes the documentation hard to write.

[shippy]

Note about terminology:

• generateTrials really does two things:
  1. generates all core trial-properties combinations (value, probability, ambiguity) evenly
  2. distributes auxilliary trial properties evenly across the generated combinations
• generateBlocks really does three things:
  1. gets trials from some source (generate, import, direct argument)
  2. randomizes order of trials
  3. divides trials into n block objects, depending on the settings.

It bears noting that generateBlocks is really generateBlocksForCondition, as it is nowhere near generating all the blocks.

On reflection, this is sufficiently confusing and difficult for documenting that I'm moving it to the Essential features milestone.

[shippy]

Related: #74.

[shippy]

Proposed new functions:

• generatePropertyCombinations, which returns a table of trials and takes the following arguments:

  • struct with "all-combinations properties," for which all possible combinations should be generated,
  • struct with "fill-in properties," which are evenly distributed among the created combinations.

  Note that this will supersede the functionality of generateTrials (which should really be renamed generateRATrials) into two calls of generatePropertyCombinations - one for probability with zero ambiguity, the other for ambiguity with 50%-probability midpoints.

• sortTrialsIntoBlocks, which returns a cell array of blocks and takes the following arguments:

  • A table of all non-catch trials to be distributed into blocks
  • Block/condition config struct with info about block count / length (to be passed to getBlockLengths - see Rewrite generateBlocks to use numBlocks instead of block.length #92)

• addCatchTrialsToBlocks, which will modify the cell array of blocks returned by sortTrialsIntoBlocks (or a single table of trials?) by injecting them at given indices (or random indices if the index is not given or NaN) into blocks at given indices.

The following functionality should receive specs:

• arrangeBlocksAcrossConditions: Given a cell array in which each element is itself a condition's cell array of blocks, arrange them randomly or in a pattern given by an order matrix (e.g. [1 1 2 2 1 1 2 2] for two conditions with four blocks each)
• getOrderAssignment: given an order matrix, some number-returning function with subject ID (...or date? or something? as argument), and some matrix-circling function, return an order matrix to be used by arrangeBlocksAcrossConditions.

[shippy]

Here's a sketch of the trial + block generation procedure for a single condition. (It works on branch 118_refactor_generation, but I have yet to rewrite any tasks to work this way.)

Trial generation

First, we generate the risk trials and ambiguity trials separately, using core properties to generate all possible combinations and complementary properties to fill out additional columns without adding new rows.

(Note that if we changed the reference-defining line to core.stakes_loss = [1 2], generateCombinations would result in twice as many combinations. Note also that since stakes_loss and reference are single-valued, it doesn't make a difference whether they're in core or complementary.)

core = struct;
core.stakes = 2:5; % Levels are translated via lookup table
core.probs = [.25 .5 .75];
core.ambigs = [.24 .5 .74];
core.stakes_loss = 1;
core.reference = 2;

complementary = struct;
complementary.colors = [1 2];

% generate risk trials and ambiguity trials separately
generateAmbig = generate;
generateAmbig.probs = 0.5; % only generate ambiguous trials with 50% midpoint
generateProb = generate;
generateProb.ambigs = 0; 

RA_combinations = [generateCombinations(probGenerate); ...
  generateCombinations(ambigGenerate)];
RA_trials = addDispersedColumns(RA_combinations, complementary);

RA_trials_all = table;
for k = 1:generate.repeats
  RA_trials_all = [RA_combinations; RA_trials_all];
end

% at this point, it might be desirable to randomize the table, 
% using e.g. the approach from `generateBlocks`:
% numTrials = height(RA_trials_all);
% RA_trials_all = RA_trials_all(randperm(numTrials), :);

We could also just load the core combinations from a CSV file (see importTrials; #109 and #112, which this might implement) and call addDispersedColumns after.

Block assignment

Using the configuration options set in #92 (do read about them there), we can easily split the single table into a cell array of blocks that runNthBlock expects:

% this assumes that `RA_trials_final` is the same for both conditions, but 
% each condition could have its own process of trial generation
RA_gains = splitTrialsIntoBlocks(RA_trials_all, RA_blockDefaults)
RA_loss = splitTrialsIntoBlocks(RA_trials_all, RA_lossConfig(RA_blockDefaults))

Finally, to get the blocks from different conditions in the right order for the task:

subjectId = 1413;
defaultOrder = [1 1 2 2 2 2 1 1]; 
% defaultOrder{k} = j denotes that k-th block should come from j-th condition
RA_orderFn = @(x) ismember(mod(x, 10), [1 2 4 9])
orderToUse = rotateBlockOrder(defaultOrder, 1334, RA_orderFn)
RA_final = orderBlocksAcrossConditions(orderToUse, RA_gains, RA_loss)

By default, rotateBlockOrder uses a simple remainder of subject ID and the number of conditions to find the right "shift" for the values of the order. The general rule for an order matrix is that it's a 1-by-m matrix of values ranging from 1 to n, where m is the number of blocks in the task and n is the number of conditions in the task. orderMatrix{m} = n means that m-th element of the matrix will be assigned from condition n.

Outstanding issues

There isn't a particularly good time to add catch trials - you'd want to do it before complementary columns are added but after the trials are separated into blocks. Some possible solutions:

• Create a function (or a class of functions) that operate on the trials embedded in the block structs
• Whenever position inside a block isn't relevant, simply import them with the rest
• Extend splitTrialsIntoBlocks to check the requisite config to see if there's a catch trial defined

I'm a fan of the latter two.

[shippy]

To-do:

• Extend splitTrialsIntoBlocks to check the config argument to see if there's a catch trial defined and if yes, include it with injectRowAtIndex (same approach as in generateBlocks)
• Optional: Devise a way to operate on each block's trials within the block struct (e.g. to add the catch trials, or to add dispersed column values only after the block split) - note that there might be no elegant vectorization available and a loop is fine
• Test this approach on an actual task (most usefully, to fix SODM in Division of blocks across the SODM beneficiary condition is wrong #133)

Unless I'm missing something, this will also provide all necessary mechanisms to implement #112.