From 5d060f6b96f4123c134eee372e0c0a2b1d2d9b7c Mon Sep 17 00:00:00 2001 From: Josh de Leeuw Date: Mon, 23 Aug 2021 13:11:32 -0400 Subject: [PATCH] rename getter methods, update docs --- docs/core_library/jspsych-core.md | 443 +++++++++--------- docs/core_library/jspsych-data.md | 2 +- packages/jspsych/src/JsPsych.ts | 16 +- packages/jspsych/src/modules/data/index.ts | 26 +- .../jspsych/src/modules/plugin-api/index.ts | 2 +- .../tests/core/timeline-variables.test.ts | 8 +- 6 files changed, 251 insertions(+), 246 deletions(-) diff --git a/docs/core_library/jspsych-core.md b/docs/core_library/jspsych-core.md index c6a1892b..8bf7bf00 100644 --- a/docs/core_library/jspsych-core.md +++ b/docs/core_library/jspsych-core.md @@ -36,111 +36,6 @@ var new_timeline = { jsPsych.addNodeToEndOfTimeline(new_timeline) ``` ---- -## jsPsych.allTimelineVariables - -```javascript -jsPsych.allTimelineVariables() -``` - -### Parameters - -None. - -### Return value - -Returns an object with all available timeline variables at this moment in the experiment, represented as `key: value` pairs. - -### Description - -This function can be used to get all the timeline variables at a particular moment in the experiment. Can be useful for annotating -data, such as in the example below. - -### Example - -```javascript -var trial = { - type: 'html-keyboard-response', - stimulus: 'Just a demo', - on_finish: function(data){ - // merge all timeline variables available at this trial into the data for this trial - Object.assign(data, jsPsych.allTimelineVariables()) - } -} -``` - ---- -## jsPsych.currentTimelineNodeID - -```javascript -jsPsych.currentTimelineNodeID() -``` - -### Parameters - -None. - -### Return value - -Returns the ID of the TimelineNode that is currently active. - -### Description - -Gets the ID of the active TimelineNode. The ID is a string that follows a specific format: - -* `"0.0"` is the ID of the first top-level TimelineNode -* `"1.0"` is the ID of the second top-level TimelineNode -* `"2.0"` is the ID of the third top-level TimelineNode, and so on... - -If a TimelineNode iterates multiple times (using the loop function, for example), then the iterations are indicated in the second number: - -* `"0.0"` is the ID of the first top-level TimelineNode during the first iteration -* `"0.1"` is the ID of the first top-level TimelineNode during the second iteration -* `"0.2"` is the ID of the first top-level TimelineNode during the third iteration, and so on... - -If TimelineNodes are nested in other TimelineNodes, then the hierarchical structure is shown with `"."`: - -* `"0.0-1.0"` is the ID of the second TimelineNode on the timeline of the first top-level TimelineNode. -* `"0.0-2.0"` is the ID of the third TimelineNode on the timeline of the first top-level TimelineNode, and so on... - -The rules about iterations apply throughout the hierarchical ID: - -* `"0.2-1.3"` is the ID of the second TimelineNode, executing for the fourth time, on the timeline of the first top-level TimelineNode, executing for the third time. - - -### Example - -```javascript -var id = jsPsych.currentTimelineNodeID(); -console.log('The current TimelineNode ID is '+id); -``` - ---- -## jsPsych.currentTrial - -```javascript -jsPsych.currentTrial() -``` - -### Parameters - -None. - -### Return value - -Returns the object describing the current trial. The object will contain all of the parameters associated with the current trial. - -### Description - -Get a description of the current trial - -### Example - -```javascript -var trial = jsPsych.currentTrial(); -console.log('The current trial is using the '+trial.type+' plugin'); -``` - --- ## jsPsych.endCurrentTimeline @@ -278,6 +173,112 @@ This method tells jsPsych that the current trial is over. It is used in all of t jsPsych.finishTrial({correct_response: true}); ``` +--- +## jsPsych.getAllTimelineVariables + +```javascript +jsPsych.getAllTimelineVariables() +``` + +### Parameters + +None. + +### Return value + +Returns an object with all available timeline variables at this moment in the experiment, represented as `key: value` pairs. + +### Description + +This function can be used to get all the timeline variables at a particular moment in the experiment. Can be useful for annotating +data, such as in the example below. + +### Example + +```javascript +var trial = { + type: 'html-keyboard-response', + stimulus: 'Just a demo', + on_finish: function(data){ + // merge all timeline variables available at this trial into the data for this trial + Object.assign(data, jsPsych.getAllTimelineVariables()) + } +} +``` + +--- +## jsPsych.getCurrentTimelineNodeID + +```javascript +jsPsych.getCurrentTimelineNodeID() +``` + +### Parameters + +None. + +### Return value + +Returns the ID of the TimelineNode that is currently active. + +### Description + +Gets the ID of the active TimelineNode. The ID is a string that follows a specific format: + +* `"0.0"` is the ID of the first top-level TimelineNode +* `"1.0"` is the ID of the second top-level TimelineNode +* `"2.0"` is the ID of the third top-level TimelineNode, and so on... + +If a TimelineNode iterates multiple times (using the loop function, for example), then the iterations are indicated in the second number: + +* `"0.0"` is the ID of the first top-level TimelineNode during the first iteration +* `"0.1"` is the ID of the first top-level TimelineNode during the second iteration +* `"0.2"` is the ID of the first top-level TimelineNode during the third iteration, and so on... + +If TimelineNodes are nested in other TimelineNodes, then the hierarchical structure is shown with `"."`: + +* `"0.0-1.0"` is the ID of the second TimelineNode on the timeline of the first top-level TimelineNode. +* `"0.0-2.0"` is the ID of the third TimelineNode on the timeline of the first top-level TimelineNode, and so on... + +The rules about iterations apply throughout the hierarchical ID: + +* `"0.2-1.3"` is the ID of the second TimelineNode, executing for the fourth time, on the timeline of the first top-level TimelineNode, executing for the third time. + + +### Example + +```javascript +var id = jsPsych.getCurrentTimelineNodeID(); +console.log('The current TimelineNode ID is '+id); +``` + +--- +## jsPsych.getCurrentTrial + +```javascript +jsPsych.getCurrentTrial() +``` + +### Parameters + +None. + +### Return value + +Returns the object describing the current trial. The object will contain all of the parameters associated with the current trial. + +### Description + +Get a description of the current trial + +### Example + +```javascript +var trial = jsPsych.getCurrentTrial(); +console.log('The current trial is using the '+trial.type+' plugin'); +``` + + --- ## jsPsych.getDisplayElement @@ -305,6 +306,70 @@ var el = jsPsych.getDisplayElement(); // hide the jsPsych display el.style.visibility = 'hidden'; ``` +--- + +## jsPsych.getInitSettings + +```javascript +jsPsych.getInitSettings() +``` + +### Parameters + +None + +### Return value + +Returns the settings object used to initialize the experiment. + +### Description + +Gets the object containing the settings for the current experiment. + +### Example + +```javascript +var settings = jsPsych.getInitSettings(); + +// check the experiment structure +console.log(JSON.stringify(settings.timeline)); +``` + + +--- + +## jsPsych.getProgress + +```javascript +jsPsych.getProgress() +``` + +### Parameters + +None. + +### Return value + +Returns an object with the following properties: + +| Property | Type | Description | +| -------------------- | ------- | ---------------------------------------- | +| total_trials | numeric | Indicates the number of trials in the experiment. Note that this does not count possible loops or skipped trials due to conditional statements. | +| current_trial_global | numeric | Returns the trial index of the current trial in a global scope. Every trial will increase this count by 1. | +| percent_complete | numeric | Estimates the percent of the experiment that is complete. Works as expected for experiments without conditional or looping timelines. For complex timelines, the percent is an approximation. | + + +### Description + +This method returns information about the length of the experiment and the subject's current location in the experiment timeline. + +### Example + +```javascript +var progress = jsPsych.getProgress(); +alert('You have completed approximately '+progress.percent_complete+'% of the experiment'); +``` + --- ## jsPsych.getProgressBarCompleted @@ -331,6 +396,60 @@ Used to get the current value of the progress bar. Works for automated and manua var progress_bar_amount = jsPsych.getProgressBarCompleted(); ``` +--- + +## jsPsych.getStartTime + +```javascript +jsPsych.getStartTime() +``` + +### Parameters + +None. + +### Return value + +Returns a `Date` object indicating when the experiment began. + +### Description + +Get the time that the experiment began. + +### Example + +```javascript +var start_time = jsPsych.getStartTime(); +``` + +--- + +## jsPsych.getTotalTime + +```javascript +jsPsych.getTotalTime() +``` + +### Parameters + +None. + +### Return value + +Returns a numeric value indicating the number of milliseconds since `jsPsych.init` was called. + +### Description + +Gets the total time the subject has been in the experiment. + +### Example + +```javascript +var time = jsPsych.getTotalTime(); +console.log(time); +``` + + --- ## jsPsych.init @@ -388,34 +507,6 @@ This method configures and starts the experiment. See any of the plugin examples in the [examples folder](https://github.com/jodeleeuw/jsPsych/tree/master/examples) in the GitHub repository. ---- - -## jsPsych.initSettings - -```javascript -jsPsych.initSettings() -``` - -### Parameters - -None - -### Return value - -Returns the settings object used to initialize the experiment. - -### Description - -Gets the object containing the settings for the current experiment. - -### Example - -```javascript -var settings = jsPsych.initSettings(); - -// check the experiment structure -console.log(JSON.stringify(settings.timeline)); -``` --- @@ -455,40 +546,6 @@ var trial = { --- -## jsPsych.progress - -```javascript -jsPsych.progress() -``` - -### Parameters - -None. - -### Return value - -Returns an object with the following properties: - -| Property | Type | Description | -| -------------------- | ------- | ---------------------------------------- | -| total_trials | numeric | Indicates the number of trials in the experiment. Note that this does not count possible loops or skipped trials due to conditional statements. | -| current_trial_global | numeric | Returns the trial index of the current trial in a global scope. Every trial will increase this count by 1. | -| percent_complete | numeric | Estimates the percent of the experiment that is complete. Works as expected for experiments without conditional or looping timelines. For complex timelines, the percent is an approximation. | - - -### Description - -This method returns information about the length of the experiment and the subject's current location in the experiment timeline. - -### Example - -```javascript -var progress = jsPsych.progress(); -alert('You have completed approximately '+progress.percent_complete+'% of the experiment'); -``` - ---- - ## jsPsych.resumeExperiment ```javascript @@ -554,32 +611,6 @@ jsPsych.setProgressBar(0.85); --- -## jsPsych.startTime - -```javascript -jsPsych.startTime() -``` - -### Parameters - -None. - -### Return value - -Returns a `Date` object indicating when the experiment began. - -### Description - -Get the time that the experiment began. - -### Example - -```javascript -var start_time = jsPsych.startTime(); -``` - ---- - ## jsPsych.timelineVariable ```javascript @@ -664,32 +695,6 @@ var procedure = { } ``` ---- - -## jsPsych.totalTime - -```javascript -jsPsych.totalTime() -``` - -### Parameters - -None. - -### Return value - -Returns a numeric value indicating the number of milliseconds since `jsPsych.init` was called. - -### Description - -Gets the total time the subject has been in the experiment. - -### Example - -```javascript -var time = jsPsych.totalTime(); -console.log(time); -``` --- diff --git a/docs/core_library/jspsych-data.md b/docs/core_library/jspsych-data.md index f9c7eca5..13ca3be9 100644 --- a/docs/core_library/jspsych-data.md +++ b/docs/core_library/jspsych-data.md @@ -124,7 +124,7 @@ Get all the data generated by a specified Timeline. ### Example ```javascript -var current_node_id = jsPsych.currentTimelineNodeID(); +var current_node_id = jsPsych.getCurrentTimelineNodeID(); var data_from_current_node = jsPsych.data.getDataByTimelineNode(current_node_id); ``` diff --git a/packages/jspsych/src/JsPsych.ts b/packages/jspsych/src/JsPsych.ts index c895b40f..5ba1009d 100644 --- a/packages/jspsych/src/JsPsych.ts +++ b/packages/jspsych/src/JsPsych.ts @@ -181,7 +181,7 @@ export class JsPsych { await this.finished; } - progress() { + getProgress() { return { total_trials: typeof this.timeline === "undefined" ? undefined : this.timeline.length(), current_trial_global: this.global_trial_index, @@ -189,11 +189,11 @@ export class JsPsych { }; } - startTime() { + getStartTime() { return this.exp_start_time; } - totalTime() { + getTotalTime() { if (typeof this.exp_start_time == "undefined") { return 0; } @@ -315,15 +315,15 @@ export class JsPsych { this.timeline.endActiveNode(); } - currentTrial() { + getCurrentTrial() { return this.current_trial; } - initSettings() { + getInitSettings() { return this.opts; } - currentTimelineNodeID() { + getCurrentTimelineNodeID() { return this.timeline.activeID(); } @@ -335,7 +335,7 @@ export class JsPsych { } } - allTimelineVariables() { + getAllTimelineVariables() { return this.timeline.allTimelineVariables(); } @@ -772,7 +772,7 @@ export class JsPsych { } private updateProgressBar() { - var progress = this.progress().percent_complete; + var progress = this.getProgress().percent_complete; this.setProgressBar(progress / 100); } diff --git a/packages/jspsych/src/modules/data/index.ts b/packages/jspsych/src/modules/data/index.ts index 064c33a2..4eb06d8a 100644 --- a/packages/jspsych/src/modules/data/index.ts +++ b/packages/jspsych/src/modules/data/index.ts @@ -33,16 +33,16 @@ export class JsPsychData { } write(data_object) { - var progress = this.jsPsych.progress(); - var trial = this.jsPsych.currentTrial(); + var progress = this.jsPsych.getProgress(); + var trial = this.jsPsych.getCurrentTrial(); //var trial_opt_data = typeof trial.data == 'function' ? trial.data() : trial.data; var default_data = { trial_type: trial.type.info.name, trial_index: progress.current_trial_global, - time_elapsed: this.jsPsych.totalTime(), - internal_node_id: this.jsPsych.currentTimelineNodeID(), + time_elapsed: this.jsPsych.getTotalTime(), + internal_node_id: this.jsPsych.getCurrentTimelineNodeID(), }; this.allData.push({ @@ -127,22 +127,22 @@ export class JsPsychData { window.addEventListener("blur", () => { var data = { event: "blur", - trial: this.jsPsych.progress().current_trial_global, - time: this.jsPsych.totalTime(), + trial: this.jsPsych.getProgress().current_trial_global, + time: this.jsPsych.getTotalTime(), }; this.interactionData.push(data); - this.jsPsych.initSettings().on_interaction_data_update(data); + this.jsPsych.getInitSettings().on_interaction_data_update(data); }); // focus event capture window.addEventListener("focus", () => { var data = { event: "focus", - trial: this.jsPsych.progress().current_trial_global, - time: this.jsPsych.totalTime(), + trial: this.jsPsych.getProgress().current_trial_global, + time: this.jsPsych.getTotalTime(), }; this.interactionData.push(data); - this.jsPsych.initSettings().on_interaction_data_update(data); + this.jsPsych.getInitSettings().on_interaction_data_update(data); }); // fullscreen change capture @@ -158,11 +158,11 @@ export class JsPsychData { document.fullscreenElement ? "fullscreenenter" : "fullscreenexit", - trial: this.jsPsych.progress().current_trial_global, - time: this.jsPsych.totalTime(), + trial: this.jsPsych.getProgress().current_trial_global, + time: this.jsPsych.getTotalTime(), }; this.interactionData.push(data); - this.jsPsych.initSettings().on_interaction_data_update(data); + this.jsPsych.getInitSettings().on_interaction_data_update(data); }; document.addEventListener("fullscreenchange", fullscreenchange); diff --git a/packages/jspsych/src/modules/plugin-api/index.ts b/packages/jspsych/src/modules/plugin-api/index.ts index 2f2168c6..827c51b4 100644 --- a/packages/jspsych/src/modules/plugin-api/index.ts +++ b/packages/jspsych/src/modules/plugin-api/index.ts @@ -7,7 +7,7 @@ import { MediaAPI } from "./MediaAPI"; import { TimeoutAPI } from "./TimeoutAPI"; export function createJointPluginAPIObject(jsPsych: JsPsych) { - const settings = jsPsych.initSettings(); + const settings = jsPsych.getInitSettings(); return Object.assign( {}, ...[ diff --git a/packages/jspsych/tests/core/timeline-variables.test.ts b/packages/jspsych/tests/core/timeline-variables.test.ts index 12479151..419f955b 100644 --- a/packages/jspsych/tests/core/timeline-variables.test.ts +++ b/packages/jspsych/tests/core/timeline-variables.test.ts @@ -365,7 +365,7 @@ describe("timeline variables are correctly evaluated", () => { }); }); -describe("jsPsych.allTimelineVariables()", () => { +describe("jsPsych.getAllTimelineVariables()", () => { test("gets all timeline variables for a simple timeline", async () => { const jsPsych = initJsPsych(); await startTimeline( @@ -376,7 +376,7 @@ describe("jsPsych.allTimelineVariables()", () => { type: htmlKeyboardResponse, stimulus: "foo", on_finish: (data) => { - var all_tvs = jsPsych.allTimelineVariables(); + var all_tvs = jsPsych.getAllTimelineVariables(); Object.assign(data, all_tvs); }, }, @@ -411,7 +411,7 @@ describe("jsPsych.allTimelineVariables()", () => { type: htmlKeyboardResponse, stimulus: "foo", on_finish: (data) => { - var all_tvs = jsPsych.allTimelineVariables(); + var all_tvs = jsPsych.getAllTimelineVariables(); Object.assign(data, all_tvs); }, }, @@ -458,7 +458,7 @@ describe("jsPsych.allTimelineVariables()", () => { { a: 2, b: 3 }, ], conditional_function: () => { - var all_tvs = jsPsych.allTimelineVariables(); + var all_tvs = jsPsych.getAllTimelineVariables(); a = all_tvs.a; b = all_tvs.b; return true;