mirror of
https://github.com/jspsych/jsPsych.git
synced 2025-05-10 11:10:54 +00:00
rename getter methods, update docs
This commit is contained in:
Josh de Leeuw
parent
2b82cab264
commit
5d060f6b96
@ -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);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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);
|
||||
```
|
||||
|
||||
|
||||
@ -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);
|
||||
}
|
||||
|
||||
|
||||
@ -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);
|
||||
|
||||
@ -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(
|
||||
{},
|
||||
...[
|
||||
|
||||
@ -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;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user