Random-parameter-set Class

Object describing common parameters to use in EVERY frame created by this randomizer. Parameter names and values are as described in the documentation for the frameType used.

[Optional] How to select a parameterSet for a participant who has previously participated in this study. Must be one of 'random' (default), 'persist', or 'rotate'. Meanings:

• "random": regardless of any previous sessions from this participant, select a parameterSet for this participant as usual (including using parameterSetWeights if provided). Default behavior.

• "persist": Continue assigning the same participant to the same parameterSet for all sessions.

• "rotate": The first time, assign parameterSet randomly (per parameterSetWeights if given); after that, each time the participant participates assign them to the next parameterSet in the list. Subtracts length of parameterSets until the 'next' index is in range.

The most recent session in which the conditions data includes an element that looks like it was generated by this same randomizer (i.e., with key ending in -frameId, like -test-trials) will always be used for assignment. Only sessions with a completed consent frame are considered, so that participants are not rotated through conditions simply due to refreshing the setup page.

Note: The "same" or "next" parameterSets are determined by the index of the previously-selected parameterSet. That is, if you were assigned to conditionNum 0 (index 0 in parameterSets) last time, you will be assigned to conditionNum 0 again this time if conditionForAdditionalSessions is "persist" and conditionNum 1 if conditionForAdditionalSessions is "rotate". So if you update the list of parameterSets in your study - e.g. to fix a bug or clarify wording - the new values will be used even for repeat participants. But be careful that you do not reorder them unless you intend to, say, swap all participants to the opposite condition on a specified date!

If the previous index is now outside the range of the parameterSets list (e.g., you used to have 6 conditions, and the participant was previously in conditionNum 5, but then you changed parameterSets to have only 3 elements) and conditionForAdditionalSessions is "persist", then the participant is assigned to the last element of parameterSets.

List of frames to be created by this randomizer. Each frame is an object with any necessary frame-specific properties specified. The kind of frame can be specified either here (per frame) or in commonFrameProperties. If a property is defined for a given frame both in this frame list and in commonFrameProperties, the value in the frame list will take precedence.

(E.g., you could include 'kind': 'normal-frame' in commmonFrameProperties, but for a single frame in frameList, include 'kind': 'special-frame'.)

Any property VALUES within any of the frames in this list which match a property NAME in the selected parameterSet will be replaced by the corresponding parameterSet value. E.g., suppose a frame in frameList is

{
   'leftImage': 'LEFTIMAGE1',
   'rightImage': 'frog.jpg',
   'size': 'IMAGESIZE'
}

and the row that has been selected randomly of parameterSets is

{
   'LEFTIMAGE1': 'toad.jpg',
   'LEFTIMAGE2': 'dog.jpg',
   'IMAGESIZE': 250
}

Then the frame would be transformed into:

{
   'leftImage': 'toad.jpg',
    'rightImage': 'frog.jpg',
    'size': 250
}

The same values may be applied across multiple frames. For instance, suppose frameList is

      [
           {
               'leftImage': 'LEFTIMAGE1',
               'rightImage': 'frog.jpg',
               'size': 'IMAGESIZE'
           },
           {
               'leftImage': 'LEFTIMAGE2',
               'rightImage': 'frog.jpg',
               'size': 'IMAGESIZE'
           }
       ]

Then the corresponding processed frames would include the values

      [
           {
               'leftImage': 'toad.jpg',
               'rightImage': 'frog.jpg',
               'size': 250
           },
           {
               'leftImage': 'dog.jpg',
               'rightImage': 'frog.jpg',
               'size': 250
           }
       ]

A property value like IMAGESIZE may be placed in a frame definition nested within another object (at any depth) or within a list and will still be replaced.

You can also use selectors to randomly sample from or permute a list given in a parameterSet. Suppose LISTVAR is defined in a parameterSet as THELIST, e.g. a list of potential stimuli. Within frames in your frameList (and in commonFrameProperties), you can use any of the following:

• Select the Nth element (0-indexed) of THELIST: (Will cause error if N >= THELIST.length)

   'parameterName': 'LISTVAR#N'

• Select (uniformly) a random element of THELIST:

   'parameterName': 'LISTVAR#RAND'

• Set parameterName to a random permutation of THELIST:

   'parameterName': 'LISTVAR#PERM'

• Select the next element in a random permutation of THELIST, which is used across all substitutions in this randomizer. This allows you, for instance, to provide a list of possible images in your parameterSet, and use a different one each frame with the subset/order randomized per participant. If more LISTVAR_UNIQ parameters than elements of THELIST are used, we loop back around to the start of the permutation generated for this randomizer.

   'parameterName': 'LISTVAR#UNIQ'

Array of parameter sets to randomly select from in order to determine the parameters for each frame in this session.

A single element of parameterSets will be applied to a given session.

[Optional] Array of weights for parameter sets; elements correspond to elements of parameterSets. The probability of selecting an element parameterSets[i] is parameterSetWeights[i]/sum(parameterSetWeights).

If not provided, all parameterSets are weighted equally.

This is intended to allow manual control of counterbalancing during data collection, e.g. to allow one condition to 'catch up' if it was randomly selected less often.

Instead of providing a single list of the same length as parameterSets, you may instead provide a list of objects specifying the weights to use within various age ranges, like this:

   'parameterSetWeights': [
       {
           'minAge': 0,
           'maxAge': 365,
           'weights': [1, 0, 1]
       },
       {
           'minAge': 365,
           'maxAge': 10000,
           'weights': [0, 1, 0]
       },
   ]

The child's age in days will be computed, and the weights used will be based on the first element of parameterSetWeights where the child falls between the min and max age. In the example above, children under one year old will be assigned to either the first or third condition; children over a year will be assigned to the second condition. This may be useful for researchers who need to balance condition assignment per age bracket. As you code data and realize you are set on 3-year-olds in condition A, for instance, you can stop assigning any more 3-year-olds to that condition.