randomization namespace

This page documents the uil.randomization namespace/module. This namespace contains many functions to randomize your stimuli. Some functions are easy to use, others are better suited in case of very specific constrains.

randomizeStimuli(original_stimuli, max_same_type=2, type_key="item_type")

Randomizes a given list of stimuli, but ensures no more than x stimuli of the same type will appear after each other.

x can be set by the max_same_type parameter

The original_stimuli parameter must be an array of objects. These objects must have a variable that denotes the type of this stimuli. The default name is ‘item_type’, this can be overriden by the optional type_key variable.

The contents of this type variable can be anything that can be compared. Strings are recommended for human readability.

Arguments:

  • original_stimuli (array.<object>) – A list of stimuli objects

  • max_same_type (int) – The max number of items of the same type that is allowed appear in succession

  • type_key (string) – The name of the variable that denotes the stimuli’s type

Returns:

randomizeStimuliConstraints(original_stimuli, constraints, max_tries=10)

Randomize the input stimuli, according to the given constraints.

A new list of stimuli will be returned if reasonably possible. The constraints are an object with a key that must also be present in the original stimuli. The value of the belonging to the key, denotes how many items with item[key] may have the same value in a row.

Arguments:

  • original_stimuli (array.<object>) – The unrandomized stimuli

  • constraints (object) – The constraints to determine how many items with the same value may be appended in a row.

  • max_tries (number) – The total number of attempts to randomize the stimuli.

Returns:

randomShuffle(original_stimuli)

Returns a copy of the input that is shuffled pseudo randomly

Arguments:

  • original_stimuli (Array)

Returns:

Array – A shuffled version of the input.

randomShuffleConstraints(original_stimuli, constraints, max_tries=10)

Randomizes the stimuli.

This function also randomizes the stimuli. This function may give a little bit more luck when your constraints are very strict or when there is an imbalance in the input. An imbalance occurs when your stimuli are: [{a:1},{a:1},{a:2},….{a:1},{a:1},{a:2}] There are twice as many ones in the stimuli compared to two’s.

This function might be more expensive compared to: uil.randomization.randomizeStimuli(Constraints).

Arguments:

  • original_stimuli (Array.<Object>)

  • constraints (Object) – The object that defines the constraints

  • max_tries (number) – A number larger or equal to 1.

Returns:

null|Array.<Object> –

stimuliMeetConstraints(stimuli, constraints)

Tests whether a shuffled array is meeting the constraints.

Arguments:

  • stimuli (Array.<object>)

  • constraints (Object)