jsPsych.randomization¶

The jsPsych.randomization module contains methods that are useful for generating random lists of trial variables.

jsPsych.randomization.factorial¶

jsPsych.randomization.factorial(factors, repetitions, unpack)

Parameters¶

Parameter	Type	Description
factors	object	The `factors` object should contain a property for each different factor. Each property-factor should have a value of an array, with each element of the array corresponding to a level of the factor.
repetitions	integer	The number of times to repeat each unique combination of the factors in the output sample.
unpack	boolean	If `true` then the output will be an object with a property for each factor in the original `factors` object. The value of each property-factor will be an array containing the levels of the factor in a random order. The order will be consistent across each property-factor (e.g., the first element of each property-factor will specify one unique combination of the factors). If `false`, then the return value will be an array of objects where each property-factor contains only a single value.

Return value¶

The return value depends on the unpack parameter. See description of the parameter above, and examples below.

Description¶

This method takes a list of factors and their levels, and creates a full factorial design by creating each unique combination of the factors. The returned set of combinations is in a random order.

Examples¶

Create full factorial design¶

var factors = {
    stimulus: ['a.jpg', 'b.jpg'],
    ms_delay: [100, 200]
}

var full_design = jsPsych.randomization.factorial(factors, 1);

/*
output:
full_design = [
    {stimulus: 'a.jpg', ms_delay: 200},
    {stimulus: 'b.jpg', ms_delay: 200},
    {stimulus: 'b.jpg', ms_delay: 100},
    {stimulus: 'a.jpg', ms_delay: 100},
]
*/

Create full factorial design with repeats¶

var factors = {
    stimulus: ['a.jpg', 'b.jpg'],
    ms_delay: [100, 200]
}

var full_design = jsPsych.randomization.factorial(factors, 2);

/*
output:
full_design = [
    {stimulus: 'b.jpg', ms_delay: 200},
    {stimulus: 'b.jpg', ms_delay: 100},
    {stimulus: 'b.jpg', ms_delay: 100},
    {stimulus: 'a.jpg', ms_delay: 100},
    {stimulus: 'a.jpg', ms_delay: 200},
    {stimulus: 'b.jpg', ms_delay: 200},
    {stimulus: 'a.jpg', ms_delay: 100},
    {stimulus: 'a.jpg', ms_delay: 200},
]
*/

Create full factorial design, unpacked¶

var factors = {
    stimulus: ['a.jpg', 'b.jpg'],
    ms_delay: [100, 200]
}

var full_design = jsPsych.randomization.factorial(factors, 1, true);

/*
output:
full_design = {
    stimulus: ['a.jpg','b.jpg','b.jpg','a.jpg'],
    ms_delay: [200, 100, 200, 100]
]
*/

jsPsych.randomization.randomID¶

jsPsych.randomization.randomID(length)

Parameters¶

Parameter	Type	Description
length	integer	The length of the randomly generated ID

Return value¶

Returns a string of length length where each character is randomly selected from the numbers 0-9 and all lowercase English letters a-z.

Description¶

Generates a random string that is likely to be unique. If length is undefined, then the string length is 32.

Example¶

console.log(jsPsych.randomization.randomID());
// outputs: "t7dwz0e713pc8juuaayyfvpkdd9un239"

console.log(jsPsych.randomization.randomID(8));
// outputs: "3xtpcbck"

jsPsych.randomization.randomInt¶

jsPsych.randomization.randomInt(lower, upper)

Parameters¶

Parameter	Type	Description
lower	integer	The smallest value it is possible to generate
upper	integer	The largest value it is possible to generate

Return value¶

An integer

Description¶

Generates a random integer from lower to upper

Example¶

console.log(jsPsych.randomization.randomInt(2,4));
// outputs: 2 or 3 or 4.

jsPsych.randomization.repeat¶

jsPsych.randomization.repeat(array, repetitions, unpack)

Parameters¶

Parameter	Type	Description
array	array	The array of values to randomize & repeat.
repetitions	integer or array	The number of times to repeat each element of the `array` in the final sample. If this parameter is defined as an integer, then each element of `array` is repeated the same number of times. This parameter can also be an array of the same length as `array`, in which case each element of `array` will be repeated the number of times defined in the corresponding position of the `repetitions` array.
unpack	boolean	If each element of `array` is an object with an equivalent set of properties, then setting `unpack` to `true` will make the return value an object with a property for each of the unique properties among the elements of the `array`. Each property in the output object will be an array containing the values for that property in the randomized order. The order will be consistent across properties. If this is `false` then the output is just an array containing a randomized order of the original `array` elements.

Return value¶

The return value depends on the unpack parameter. See description of the parameter above, and examples below.

Description¶

This method takes an array of values and generates a new random order of the array, with the option of repeating each element of the array a specified number of times.

If the array elements are objects with the same set of properties, then this method can optionally return a single object where each property is a randomized order of the properties defined in the original set of objects. This is useful for randomizing sets of parameters that are used to define a jsPsych block.

Examples¶

Shuffle an array, no repeats¶

var myArray = [1,2,3,4,5];
var shuffledArray = jsPsych.randomization.repeat(myArray, 1);
// output: shuffledArray = [3,2,4,1,5]

Shuffle an array with repeats¶

var myArray = [1,2,3,4,5];
var shuffledArray = jsPsych.randomization.repeat(myArray, 2);
// output: shuffledArray = [1,3,4,2,2,4,5,1,5,3]

Shuffle an array of objects¶

var trial1 = {
    stimulus: 'img/faceA.jpg',
    correct_key: 'p',
    person_name: 'Joe'
}

var trial2 = {
    stimulus: 'img/faceB.jpg',
    correct_key: 'p',
    person_name: 'Fred'
}

var trial3 = {
    stimulus: 'img/faceC.jpg',
    correct_key: 'q',
    person_name: 'Mary'
}

var myArray = [ trial1, trial2, trial3 ];
var shuffledArray = jsPsych.randomization.repeat(myArray, 2);

// output: shuffledArray = [ trial1, trial3, trial3, trial2, trial1, trial2 ]

Shuffle an array of objects, with unpack¶

var trial1 = {
    stimulus: 'img/faceA.jpg',
    correct_key: 'p',
    person_name: 'Joe'
}

var trial2 = {
    stimulus: 'img/faceB.jpg',
    correct_key: 'p',
    person_name: 'Fred'
}

var trial3 = {
    stimulus: 'img/faceC.jpg',
    correct_key: 'q',
    person_name: 'Mary'
}

var myArray = [ trial1, trial2, trial3 ];
var shuffledArray = jsPsych.randomization.repeat(myArray, 2, true);

/*
output: shuffledArray = {
    stimulus: ['img/faceB.jpg','img/faceA.jpg','img/faceC.jpg','img/faceA.jpg','img/faceC.jpg','img/faceB.jpg'],
    correct_key: ['p', 'p', 'q', 'p', 'q', 'p'],
    person_name: ['Fred', 'Joe', 'Mary', 'Joe', 'Mary', 'Fred']
}
*/

jsPsych.randomization.sampleBernoulli¶

jsPsych.randomization.sampleBernoulli(p)

Parameters¶

Parameter	Type	Description
p	number	Probability of sampling 1

Return value¶

Returns 0 with probability 1-p and 1 with probability p.

Description¶

Generates a random sample from a Bernoulli distribution.

Examples¶

Sample a value¶

if(jsPsych.randomization.sampleBernoulli(0.8)){
    // this happens 80% of the time
} else {
    // this happens 20% of the time
}

jsPsych.randomization.sampleExGaussian¶

jsPsych.randomization.sampleExGaussian(mean, standard_deviation, rate, positive=false)

Parameters¶

Parameter	Type	Description
mean	number	Mean of the normal distribution component of the exGaussian
standard_deviation	number	Standard deviation of the normal distribution component of the exGaussian
rate	number	Rate of the exponential distribution component of the exGaussian
positive	bool	If `true` sample will be constrained to > 0.

Return value¶

A random sample from the distribution

Description¶

Generates a random sample from an exponentially modified Gaussian distribution.

Examples¶

Sample a value¶

var rand_sample_exg = jsPsych.randomization.sampleExGaussian(500, 100, 0.01);

jsPsych.randomization.sampleExponential¶

jsPsych.randomization.sampleExponential(rate)

Parameters¶

Parameter	Type	Description
rate	number	Rate of the exponential distribution

Return value¶

A random sample from the distribution

Description¶

Generates a random sample from an exponential distribution.

Examples¶

Sample a value¶

var rand_sample_exg = jsPsych.randomization.sampleExponential(0.01);

jsPsych.randomization.sampleNormal¶

jsPsych.randomization.sampleNormal(mean, standard_deviation)

Parameters¶

Parameter	Type	Description
mean	number	Mean of the normal distribution
standard_deviation	number	Standard deviation of the normal distribution

Return value¶

A random sample from the distribution

Description¶

Generates a random sample from a normal distribution.

Examples¶

Sample a value¶

var rand_sample_exg = jsPsych.randomization.sampleNormal(500, 250);

jsPsych.randomization.sampleWithReplacement¶

jsPsych.randomization.sampleWithReplacement(array, sampleSize, weights)

Parameters¶

Parameter	Type	Description
array	array	The array of values to sample from
sampleSize	numeric	The number of samples to draw
weights	array	The relative weight of each element in `array`. This array is normalized, so the values do not need to sum to 1. The length must match the length of `array`.

Return value¶

An array containing the sample.

Description¶

This method returns a sample drawn at random from a set of values with replacement. The relative probability of drawing each item can be controlled by specifying the weights.

Examples¶

Sample with equal probability¶

var myArray = [1,2,3,4,5];
var sample = jsPsych.randomization.sampleWithReplacement(myArray, 10);
// output: sample = [3, 1, 2, 2, 5, 1, 4, 3, 1, 5];

Sample with unequal probability¶

var myArray = [1,2,3,4,5];
var sample = jsPsych.randomization.sampleWithReplacement(myArray, 10, [6,1,1,1,1]);
// output: sample = [3, 4, 5, 1, 2, 1, 3, 1, 1, 1];

jsPsych.randomization.sampleWithoutReplacement¶

jsPsych.randomization.sampleWithoutReplacement(array, sampleSize)

Parameters¶

Parameter	Type	Description
array	array	The array of values to sample from
sampleSize	numeric	The number of samples to draw

Return value¶

An array containing the sample.

Description¶

This method returns a sample drawn at random from a set of values without replacement. The sample size must be less than or equal to the length of the array.

Examples¶

Sample without replacement¶

var myArray = [1,2,3,4,5];
var sample = jsPsych.randomization.sampleWithoutReplacement(myArray, 2);
// output: sample = [3,2];

jsPsych.randomization.shuffle¶

jsPsych.randomization.shuffle(array)

Parameters¶

Parameter	Type	Description
array	array	The array of values to shuffle

Return value¶

Returns an array with the same elements as the input array in a random order.

Description¶

A simple method for shuffling the order of an array.

Examples¶

Shuffle an array¶

var myArray = [1,2,3,4,5];
var shuffledArray = jsPsych.randomization.shuffle(myArray);
// output: shuffledArray = [3,2,4,1,5]

jsPsych.randomization.shuffleNoRepeats¶

jsPsych.randomization.shuffleNoRepeats(array, equalityTest)

Parameters¶

Parameter	Type	Description
array	array	The array of values to shuffle
equalityTest	function	A function to use to evaluate the equality of neighbors in the array. The function should accept two parameters, which are the two elements to be tested. It should return `true` if they are equal and `false` if not. The default function, if none is specified, is to use the `===` operator. This will work for primitive values, but fail for Objects and Arrays. An example function is given below in the examples.

Return value¶

Returns an array with the same elements as the input array in a random order, with no repeating neighbors.

Description¶

Shuffle an array, ensuring that neighboring elements in the array are different.

Warning: if you provide an array that has very few valid permutations with no neighboring elements, then this method will fail and cause the browser to hang.

Examples¶

Basic example¶

var myArray = [1,2,3,4,5,1,2,3,4,5,1,2,3,4,5];
var shuffledArray = jsPsych.randomization.shuffleNoRepeats(myArray);
// output: shuffledArray = [2, 3, 5, 1, 2, 4, 1, 5, 4, 1, 3, 5, 4, 3, 2]

Custom equalityTest¶

var myObjects = [
  {color:"blue"},
    {color:"red"},
    {color:"yellow"},
    {color:"orange"}
];

var repeatedSet = jsPsych.randomization.repeat(myObjects,3);
var shuffled = jsPsych.randomization.shuffleNoRepeats(repeatedSet, function(a,b) { return a.color === b.color });

// console.log(JSON.stringify(shuffled))
// "[{"color":"red"},{"color":"yellow"},{"color":"blue"},{"color":"yellow"},{"color":"orange"},{"color":"red"},{"color":"yellow"},{"color":"orange"},{"color":"blue"},{"color":"orange"},{"color":"red"},{"color":"blue"}]"