Merge pull request #155 from jodeleeuw/dev

4.3 merge

docs/markdown_docs/core_library/jspsych-data.md

@@ -2,6 +2,46 @@
 
 The jsPsych.data module contains functions for interacting with the data generated by jsPsych plugins.
 
+---
+## jsPsych.data.addDataToLastTrial
+
+```
+jsPsych.data.addDataToLastTrial(data)
+```
+
+### Parameters
+
+Parameter | Type | Description
+----------|------|------------
+data | object | Object of key: value pairs to add to the data from the last trial.
+
+### Return value
+
+Returns nothing.
+
+### Description
+
+This method appends data to the data recorded by the last trial. It's particularly useful when combined with the `on_finish` event handler for a trial, as shown in the example below.
+
+
+### Examples
+
+#### Evaluate a response and add to data
+```javascript
+var block = {
+	type: 'single-stim',
+	stimuli: ['img/happy_face_1.jpg', 'img/sad_face_1.jpg'],
+	choices: [89,78], // Y or N
+	prompt: '<p class="center-content">Have you seen this face before? Y or N.</p>',
+	on_finish: function(trial_data){
+		// let's imagine that the correct answer is NO for both trials
+		var correct = (trial_data.key_press == 78);
+		jsPsych.data.addDataToLastTrial({correct: correct});
+	}
+}
+```
+
+
 ---
 ## jsPsych.data.addProperties
 

docs/markdown_docs/core_library/jspsych-pluginAPI.md

@@ -100,16 +100,21 @@ plugin.create = function(params) {
 ## jsPsych.pluginAPI.getKeyboardResponse
 
 ```
-jsPsych.pluginAPI.getKeyboardResponse(callback_function, valid_responses, rt_method, persist)
+jsPsych.pluginAPI.getKeyboardResponse(parameters)
 ```
 
 ### Parameters
 
+The method accepts an object of parameter values (see example below). The valid keys for this object are listed in the table below.
+
 Parameter | Type | Description
 ----------|------|------------
 callback_function | function | The function to execute whenever a valid keyboard response is generated.
 valid_responses | array | An array of key codes or character strings representing valid responses. Responses not on the list will be ignored. An empty array indicates that all responses are acceptable.
-rt_method | string | Indicates which method of recording time to use. The `'date'` method uses calls to `(new Date()).getTime()` to record timing information. The `'performance'` method uses calls to `performance.now()`, which is a more modern JavaScript feature. The `'performance'` approach is [not supported by all the major browsers yet](http://caniuse.com/#search=performance), but adoption rates are increasing.
+rt_method | string | Indicates which method of recording time to use. The `'date'` method uses calls to `(new Date()).getTime()` to record timing information. The `'performance'` method uses calls to `performance.now()`, which is a more modern JavaScript feature. The `'performance'` approach is [not supported by all the major browsers yet](http://caniuse.com/#search=performance), but adoption rates are increasing. The `audio` method is used in conjuction with an `audio_context` (set as an additional parameter). This uses the clock time of the `audio_context` when audio stimuli are being played.
+audio_context | AudioContext object | The AudioContext of the audio file that is being played.
+audio_context_start_time | numeric | The scheduled time of the sound file in the AudioContext. This will be used as the start time.
+allow_held_key | boolean | If `true`, then responses will be registered from keys that are being held down. If `false`, then a held key can only register a response the first time that `getKeyboardResponse` is called for that key. For example, if a participant holds down the `A` key before the experiment starts, then the first time `getKeyboardResponse` is called, the `A` will register as a key press. However, any future calls to `getKeyboardResponse` will not register the `A` until the participant releases the key and presses it again.
 persist | boolean | If false, then the keyboard listener will only trigger the first time a valid key is pressed. If true, then it will trigger every time a valid key is pressed until it is explicitly cancelled by `jsPsych.pluginAPI.cancelKeyboardResponse` or `jsPsych.pluginAPI.cancelAllKeyboardResponses`.
 
 ### Return value
@@ -131,7 +136,12 @@ var after_response = function(info){
 	alert('You pressed key '+info.key+' after '+info.rt+'ms');
 }
 
-jsPsych.pluginAPI.getKeyboardResponse(after_response, [], 'date', false);
+jsPsych.pluginAPI.getKeyboardResponse({
+  callback_function:after_response,
+  valid_responses: [],
+  rt_method: 'date',
+  persist: false
+});
 ```
 
 #### Get a responses from a key until the letter Q is pressed
@@ -145,7 +155,12 @@ var after_response = function(info){
 	}
 }
 
-var listener = jsPsych.pluginAPI.getKeyboardResponse(after_response, [], 'date', true);
+var listener = jsPsych.pluginAPI.getKeyboardResponse({
+  callback_function:after_response,
+  valid_responses: [], 
+  rt_method: 'date',
+  persist: true
+});
 ```
 
 ---

docs/markdown_docs/core_library/jspsych-randomization.md

@@ -275,3 +275,56 @@ 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
+
+```javascript
+
+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
+
+```javascript
+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"}]"
+```

docs/markdown_docs/core_library/overview.md

@@ -21,6 +21,7 @@ Every jsPsych experiment utilizes the core library (contained in the `jspsych.js
 
 ### [Data module](jspsych-data.md)
 
+* [jsPsych.data.addDataToLastTrial](jspsych-data.md#jspsychdataadddatatolasttrial)
 * [jsPsych.data.addProperties](jspsych-data.md#jspsychdataaddproperties)
 * [jsPsych.data.dataAsCSV](jspsych-data.md#jspsychdatadataascsv)
 * [jsPsych.data.displayData](jspsych-data.md#jspsychdatadisplaydata)
@@ -43,6 +44,7 @@ Every jsPsych experiment utilizes the core library (contained in the `jspsych.js
 * [jsPsych.randomization.repeat](jspsych-randomization.md#jspsychrandomizationrepeat)
 * [jsPsych.randomization.sample](jspsych-randomization.md#jspsychrandomizationsample)
 * [jsPsych.randomization.shuffle](jspsych-randomization.md#jspsychrandomizationshuffle)
+* [jsPsych.randomization.shuffleNoRepeats](jspsych-randomization.md#jspsychrandomizationshufflenorepeats)
 
 ### [PluginAPI module](jspsych-pluginAPI.md)
 

docs/markdown_docs/plugins/jspsych-categorize.md

@@ -18,8 +18,12 @@ incorrect_text | string | "Wrong." | String to show when the wrong answer is giv
 prompt | string | "" | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g. which key to press).
 force_correct_button_press | boolean | false | If set to true, then the subject must press the correct response key after feedback is given in order to advance to the next trial.
 show_stim_with_feedback | boolean | true | If set to true, then the stimulus will be shown during feedback. If false, then only the text feedback will display during feedback.
+show_feedback_on_timeout | boolean | false | If true, then category feedback will be displayed for an incorrect response after a timeout (timing_response is exceeded). If false, then a timeout message will be shown.
+timeout_message | string | "Please respond faster." | The message to show on a timeout non-response.
 timing_stim | numeric | -1 | How long to show the stimulus for (milliseconds). If -1, then the stimulus is shown until a response is given.
 timing_feedback_duration | numeric | 2000 | How long to show the feedback for (milliseconds).
+timing_response | numeric | -1 | The maximum time allowed for a response. If -1, then the experiment will wait indefinitely for a response.
+
 
 ## Data Generated
 

docs/markdown_docs/plugins/jspsych-survey-text.md

@@ -10,6 +10,8 @@ Parameter | Type | Default Value | Description
 ----------|------|---------------|------------
 questions | array | *undefined* | Each array is an array of strings. The strings are the prompts for the subject to respond to. Each string gets its own response field. Each set of strings (inner arrays) will be presented on the same page (trial). The length of the outer array sets the number of trials in the block.
 preamble | string | empty string | HTML formatted string to display at the top of the page above all the questions.
+rows | array | 1 | The number of rows for the response text box. Array dimensions must match `questions` array, with a numeric value for each entry indicating the number of rows for that question's box.
+columns | array | 40 | The number of columns for the response text box. Array dimensions must match `questions` array, with a numeric value for each entry indicating the number of columns for that question's box.
 
 ## Data Generated
 
@@ -34,3 +36,18 @@ var survey_block = {
     questions: [page_1_questions, page_2_questions],
 };
 ```
+
+### Custom number of rows and columns
+
+```javascript
+// defining groups of questions that will go together.
+var page_1_questions = ["How old are you?", "Where were you born?"];
+var page_2_questions = ["What is your favorite food?"];
+
+var survey_block = {
+    type: 'survey-text',
+    questions: [page_1_questions, page_2_questions],
+    rows: [[5,3],[2]],
+    columns: [[40,50],[60]]
+};
+```