From 36e64efbfb6a5c5df3e75b99d3be06cea4d221bc Mon Sep 17 00:00:00 2001 From: bjoluc Date: Tue, 12 Sep 2023 21:31:37 +0200 Subject: [PATCH 1/2] Add docs page for the `utils` module --- docs/reference/jspsych-utils.md | 93 +++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 94 insertions(+) create mode 100644 docs/reference/jspsych-utils.md diff --git a/docs/reference/jspsych-utils.md b/docs/reference/jspsych-utils.md new file mode 100644 index 0000000000..1c567298c8 --- /dev/null +++ b/docs/reference/jspsych-utils.md @@ -0,0 +1,93 @@ +# jsPsych.utils + +The jsPsych.utils module contains utility functions that might turn out useful at one place or the other. + +--- + +## jsPsych.utils.unique + +```javascript +jsPsych.utils.unique(array) +``` + +### Parameters + +| Parameter | Type | Description | +| --------- | ----- | ------------------------------ | +| array | Array | An array of arbitrary elements | + +### Return value + +An array containing all elements from the input array, but without duplicate elements + +### Description + +This function takes an array and returns a copy of that array with all duplicate elements removed. + +### Example + +```javascript +jsPsych.utils.unique(["a", "b", "b", 1, 1, 2]) // returns ["a", "b", 1, 2] +``` + +--- + +## jsPsych.utils.deepCopy + +```javascript +jsPsych.utils.deepCopy(object); +``` + +### Parameters + +| Parameter | Type | Description | +| --------- | --------------- | ---------------------------- | +| object | Object or Array | An arbitrary object or array | + +### Return value + +A deep copy of the provided object or array + +### Description + +This function takes an arbitrary object or array and returns a deep copy of it, i.e. all child objects or arrays are recursively copied too. + +### Example + +```javascript +var myObject = { nested: ["array", "of", "elements"] }; +var deepCopy = jsPsych.utils.deepCopy(myObject); +deepCopy.nested[2] = "thingies"; +console.log(myObject.nested[2]) // still logs "elements" +``` + +--- + +## jsPsych.utils.deepMerge + +```javascript +jsPsych.utils.deepMerge(object1, object2); +``` + +### Parameters + +| Parameter | Type | Description | +| --------- | ------ | --------------- | +| object1 | Object | Object to merge | +| object2 | Object | Object to merge | + +### Return value + +A deep copy of `object1` with all the (nested) properties from `object2` filled in + +### Description + +This function takes two objects and recursively merges them into a new object. If both objects define the same (nested) property, the property value from `object2` takes precedence. + +### Example + +```javascript +var object1 = { a: 1, b: { c: 1, d: 2 } }; +var object2 = { b: { c: 2 }, e: 3 }; +jsPsych.utils.deepMerge(object1, object2); // returns { a: 1, b: { c: 2, d: 2 }, e: 3 } +``` diff --git a/mkdocs.yml b/mkdocs.yml index b172c2993e..214b7198cc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,6 +70,7 @@ nav: - 'jsPsych.data': 'reference/jspsych-data.md' - 'jsPsych.randomization': 'reference/jspsych-randomization.md' - 'jsPsych.turk': 'reference/jspsych-turk.md' + - 'jsPsych.utils': 'reference/jspsych-utils.md' - 'jsPsych.pluginAPI': 'reference/jspsych-pluginAPI.md' - Plugins: - 'List of Plugins': 'plugins/list-of-plugins.md' From 8834532fc9ce12c250acee97f147fbd215019400 Mon Sep 17 00:00:00 2001 From: jade <101148768+jadeddelta@users.noreply.github.com> Date: Sat, 11 Jan 2025 11:31:25 -0700 Subject: [PATCH 2/2] add `deepCopy` warning messages for randomization/sample functions --- docs/reference/jspsych-randomization.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/reference/jspsych-randomization.md b/docs/reference/jspsych-randomization.md index 49ad0e5c5d..872f8082c8 100644 --- a/docs/reference/jspsych-randomization.md +++ b/docs/reference/jspsych-randomization.md @@ -89,7 +89,7 @@ output: full_design = { stimulus: ['a.jpg','b.jpg','b.jpg','a.jpg'], ms_delay: [200, 100, 200, 100] -] +} */ ``` @@ -182,6 +182,8 @@ This method takes an array of values and generates a new random order of the arr 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. +This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy). + ### Examples #### Shuffle an array, no repeats @@ -414,6 +416,8 @@ An array containing the sample. 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`. +This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy). + ### Examples #### Sample with equal probability @@ -455,6 +459,8 @@ An array containing the sample. 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. +This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy). + ### Examples #### Sample without replacement @@ -532,6 +538,8 @@ Returns an array with the same elements as the input array in a random order. A simple method for shuffling the order of an array. +This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy). + ### Examples #### Shuffle an array @@ -565,6 +573,8 @@ Returns an array with the same elements as the input array in a random order, wi Shuffle an array, ensuring that neighboring elements in the array are different. +This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy). + *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