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.setSeed¶
jsPsych.randomization.setSeed(seed)
Parameters¶
| Parameter | Type | Description |
|---|---|---|
| seed | string | A seed for the random number generator |
Return value¶
Returns the seed value.
Description¶
This function will override the behavior of Math.random() to produce a seedable pseudo random number generator.
It uses the seedrandom package.
Note that calling setSeed() will change how Math.random() behaves for the entire document.
If you have non-jsPsych components on the page that use Math.random() they will be affected.
Using setSeed() without passing in a seed will generate a random 32-bit seed.
The seed value will be returned from the function call, allowing you to save it in the data for the experiment if needed.
Examples¶
Use a random 32-bit seed and save to data¶
const seed = jsPsych.randomization.setSeed();
jsPsych.data.addProperties({
rng_seed: seed
});
Use your own seed¶
jsPsych.randomization.setSeed("jspsych");
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"}]"