HoshinoKoji/psychojs
1
0
Fork 0
mirror of https://github.com/psychopy/psychojs.git synced 2025-05-10 10:40:54 +00:00
Code Actions Packages Releases Activity
1512ecfdc9
psychojs/docs/module-data.TrialHandler.html
Alain Pitiot 1512ecfdc9 various edits
2018-12-28 13:43:48 +01:00

2207 lines
28 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: TrialHandler</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Class: TrialHandler</h1>
<section>
<header>
<h2><span class="attribs"><span class="type-signature"></span></span>
<span class="ancestors"><a href="module-data.html">data</a>.</span>TrialHandler<span class="signature">(options)</span><span class="type-signature"></span></h2>
<div class="class-description"><p>A Trial Handler handles the importing and sequencing of conditions.</p></div>
</header>
<article>
<div class="container-overview">
<h2>Constructor</h2>
<h4 class="name" id="TrialHandler"><span class="type-signature"></span>new TrialHandler<span class="signature">(options)</span><span class="type-signature"></span></h4>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>options</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="description last">
<h6>Properties</h6>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>psychoJS</code></td>
<td class="type">
<span class="param-type"><a href="module-core.PsychoJS.html">module:core.PsychoJS</a></span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">the PsychoJS instance</td>
</tr>
<tr>
<td class="name"><code>trialList</code></td>
<td class="type">
<span class="param-type">Array.&lt;Object></span>
|
<span class="param-type">String</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
[undefined]
</td>
<td class="description last">if it is a string, we treat it as the name of a condition resource</td>
</tr>
<tr>
<td class="name"><code>nReps</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">number of repetitions</td>
</tr>
<tr>
<td class="name"><code>method</code></td>
<td class="type">
<span class="param-type"><a href="module-data.TrialHandler.html#.Method">module:data.TrialHandler.Method</a></span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">the trial method</td>
</tr>
<tr>
<td class="name"><code>extraInfo</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">additional information to be stored alongside the trial data, e.g. session ID, participant ID, etc.</td>
</tr>
<tr>
<td class="name"><code>seed</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">seed for the random number generator</td>
</tr>
<tr>
<td class="name"><code>autoLog</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
false
</td>
<td class="description last">whether or not to log</td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line30">line 30</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Extends</h3>
<ul>
<li>PsychObject</li>
</ul>
<h3 class="subsection-title">Members</h3>
<h4 class="name" id=".Method"><span class="type-signature">(static, readonly) </span>Method<span class="type-signature"> :Symbol</span></h4>
<div class="description">
TrialHandler method
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Symbol</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>SEQUENTIAL</code></td>
<td class="type">
<span class="param-type">Symbol</span>
</td>
<td class="description last">Conditions are presented in the order they are given.</td>
</tr>
<tr>
<td class="name"><code>RANDOM</code></td>
<td class="type">
<span class="param-type">Symbol</span>
</td>
<td class="description last">Conditions are shuffled within each repeat.</td>
</tr>
<tr>
<td class="name"><code>FULL_RANDOM</code></td>
<td class="type">
<span class="param-type">Symbol</span>
</td>
<td class="description last">Conditions are fully randomised across all repeats.</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line444">line 444</a>
</li></ul></dd>
</dl>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id=".importConditions"><span class="type-signature">(static) </span>importConditions<span class="signature">(serverManager, resourceName, selection<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Object}</span></h4>
<div class="description">
Import a list of conditions from a .xls, .xlsx, .odp, or .csv resource.
<p>The output is suitable as an input to 'TrialHandler', 'trialTypes' or
'MultiStairHandler' as a 'conditions' list.</p>
<p>The resource should contain one row per type of trial needed and one column
for each parameter that defines the trial type. The first row should give
parameter names, which should:
<ul>
<li>be unique</li>
<li>begin with a letter (upper or lower case)</li>
<li>contain no spaces or other punctuation (underscores are permitted)</li>
</ul></p>
<p>Note that we only consider the first worksheet for .xls, .xlsx and .odp resource.</p>
<p> 'selection' is used to select a subset of condition indices to be used
It can be a single integer, an array of indices, or a string to be parsed, e.g.:
5
[1,2,3,10]
'1,5,10'
'1:2:5'
'5:'
'-5:-2, 9, 11:5:22'
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>serverManager</code></td>
<td class="type">
<span class="param-type"><a href="module-core.ServerManager.html">module:core.ServerManager</a></span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">the server manager</td>
</tr>
<tr>
<td class="name"><code>resourceName</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">the name of the resource containing the list of conditions, which must have been registered with the server manager.</td>
</tr>
<tr>
<td class="name"><code>selection</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
null
</td>
<td class="description last">the selection</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line282">line 282</a>
</li></ul></dd>
</dl>
<h5>Throws:</h5>
<dl>
<dt>
<div class="param-desc">
Throws an exception if importing the conditions failed.
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Object</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
the parsed conditions as an array of 'object as map'
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Object</span>
</dd>
</dl>
<h4 class="name" id="_prepareTrialList"><span class="type-signature">(protected) </span>_prepareTrialList<span class="signature">(trialList)</span><span class="type-signature"></span></h4>
<div class="description">
Prepare the trial list.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>trialList</code></td>
<td class="type">
<span class="param-type">Array.&lt;Object></span>
|
<span class="param-type">String</span>
</td>
<td class="description last">a list of trials, or the name of a condition resource</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line340">line 340</a>
</li></ul></dd>
</dl>
<h4 class="name" id="addData"><span class="type-signature"></span>addData<span class="signature">(key, value)</span><span class="type-signature"></span></h4>
<div class="description">
Add a key/value pair to data about the current trial held by the experiment handler
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>key</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="description last">the key</td>
</tr>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="description last">the value</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line241">line 241</a>
</li></ul></dd>
</dl>
<h4 class="name" id="getAttributes"><span class="type-signature"></span>getAttributes<span class="signature">()</span><span class="type-signature"> &rarr; {Array.string}</span></h4>
<div class="description">
Get the attributes of the trials.
<p>Note: we assume that all trials in the trialList share the same attributes
and consequently consider only the attributes of the first trial.</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line182">line 182</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
the attributes
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Array.string</span>
</dd>
</dl>
<h4 class="name" id="getCurrentTrial"><span class="type-signature"></span>getCurrentTrial<span class="signature">()</span><span class="type-signature"> &rarr; {Object}</span></h4>
<div class="description">
Get the current trial.
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line200">line 200</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
the current trial
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Object</span>
</dd>
</dl>
<h4 class="name" id="getEarlierTrial"><span class="type-signature"></span>getEarlierTrial<span class="signature">(n<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Object|undefined}</span></h4>
<div class="description">
Get the nth previous trial.
<p> Note: this is useful for comparisons in n-back tasks.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>n</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
-1
</td>
<td class="description last">increment</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line229">line 229</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
the past trial or undefined if attempting to go prior to the first trial.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Object</span>
|
<span class="param-type">undefined</span>
</dd>
</dl>
<h4 class="name" id="getFutureTrial"><span class="type-signature"></span>getFutureTrial<span class="signature">(n<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Object|undefined}</span></h4>
<div class="description">
Get the nth future or past trial, without advancing through the trial list.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>n</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
1
</td>
<td class="description last">increment</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line213">line 213</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
the future trial (if n is positive) or past trial (if n is negative)
or undefined if attempting to go beyond the last trial.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Object</span>
|
<span class="param-type">undefined</span>
</dd>
</dl>
<h4 class="name" id="getTrialIndex"><span class="type-signature"></span>getTrialIndex<span class="signature">()</span><span class="type-signature"> &rarr; {number}</span></h4>
<div class="description">
Get the trial index.
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line158">line 158</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
the current trial index
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">number</span>
</dd>
</dl>
<h4 class="name" id="setTrialIndex"><span class="type-signature"></span>setTrialIndex<span class="signature">(index)</span><span class="type-signature"></span></h4>
<div class="description">
Set the trial index.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>index</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">the new trial index</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line168">line 168</a>
</li></ul></dd>
</dl>
<h4 class="name" id="Symbol.iterator"><span class="type-signature"></span>Symbol.iterator<span class="signature">()</span><span class="type-signature"></span></h4>
<div class="description">
Iterator over the trial sequence.
<p>This makes it possible to iterate over all trials.</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="data_TrialHandler.js.html">data/TrialHandler.js</a>, <a href="data_TrialHandler.js.html#line117">line 117</a>
</li></ul></dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>let handler = new TrialHandler({nReps: 5});
for (const thisTrial of handler) { console.log(thisTrial); }</code></pre>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Modules</h3><ul><li><a href="module-core.html">core</a></li><li><a href="module-data.html">data</a></li><li><a href="module-sound.html">sound</a></li><li><a href="module-util.html">util</a></li><li><a href="module-visual.html">visual</a></li></ul><h3>Classes</h3><ul><li><a href="module-core.BuilderKeyResponse.html">BuilderKeyResponse</a></li><li><a href="module-core.EventManager.html">EventManager</a></li><li><a href="module-core.GUI.html">GUI</a></li><li><a href="module-core.MinimalStim.html">MinimalStim</a></li><li><a href="module-core.Mouse.html">Mouse</a></li><li><a href="module-core.PsychoJS.html">PsychoJS</a></li><li><a href="module-core.ServerManager.html">ServerManager</a></li><li><a href="module-core.Window.html">Window</a></li><li><a href="module-data.ExperimentHandler.html">ExperimentHandler</a></li><li><a href="module-data.TrialHandler.html">TrialHandler</a></li><li><a href="module-sound.Sound.html">Sound</a></li><li><a href="module-sound.TonePlayer.html">TonePlayer</a></li><li><a href="module-sound.TrackPlayer.html">TrackPlayer</a></li><li><a href="module-util.Clock.html">Clock</a></li><li><a href="module-util.Color.html">Color</a></li><li><a href="module-util.CountdownTimer.html">CountdownTimer</a></li><li><a href="module-util.EventEmitter.html">EventEmitter</a></li><li><a href="module-util.Logger.html">Logger</a></li><li><a href="module-util.MonotonicClock.html">MonotonicClock</a></li><li><a href="module-util.PsychObject.html">PsychObject</a></li><li><a href="module-util.Scheduler.html">Scheduler</a></li><li><a href="module-visual.ImageStim.html">ImageStim</a></li><li><a href="module-visual.MovieStim.html">MovieStim</a></li><li><a href="module-visual.Rect.html">Rect</a></li><li><a href="module-visual.ShapeStim.html">ShapeStim</a></li><li><a href="module-visual.Slider.html">Slider</a></li><li><a href="module-visual.TextStim.html">TextStim</a></li><li><a href="module-visual.VisualStim.html">VisualStim</a></li></ul><h3>Mixins</h3><ul><li><a href="module-core.WindowMixin.html">WindowMixin</a></li><li><a href="module-util.ColorMixin.html">ColorMixin</a></li></ul><h3>Interfaces</h3><ul><li><a href="module-sound.SoundPlayer.html">SoundPlayer</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Fri Dec 28 2018 13:41:42 GMT+0100 (CET)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>
View Git Blame Copy Permalink