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
3b0308a77f
psychojs/docs/data_QuestHandler.js.html
Alain Pitiot b07d8f5b0e DOC updated the documentation
2022-05-23 12:31:01 +02:00

444 lines
15 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Source: data/QuestHandler.js</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">Source: data/QuestHandler.js</h1>
<section>
<article>
<pre class="prettyprint source linenums"><code>/** @module data */
/**
* Quest Trial Handler
*
* @author Alain Pitiot &amp; Thomas Pronk
* @version 2021.2.0
* @copyright (c) 2017-2020 Ilixa Ltd. (http://ilixa.com) (c) 2020-2021 Open Science Tools Ltd. (https://opensciencetools.org)
* @license Distributed under the terms of the MIT License
*/
import {TrialHandler} from "./TrialHandler.js";
/**
* &lt;p>A Trial Handler that implements the Quest algorithm for quick measurement of
psychophysical thresholds. QuestHandler relies on the [jsQuest]{@link https://github.com/kurokida/jsQUEST} library, a port of Prof Dennis Pelli's QUEST algorithm by [Daiichiro Kuroki]{@link https://github.com/kurokida}.&lt;/p>
*
* @class module.data.QuestHandler
* @extends TrialHandler
* @param {Object} options - the handler options
* @param {module:core.PsychoJS} options.psychoJS - the PsychoJS instance
* @param {string} options.varName - the name of the variable / intensity / contrast / threshold manipulated by QUEST
* @param {number} options.startVal - initial guess for the threshold
* @param {number} options.startValSd - standard deviation of the initial guess
* @param {number} options.minVal - minimum value for the threshold
* @param {number} options.maxVal - maximum value for the threshold
* @param {number} [options.pThreshold=0.82] - threshold criterion expressed as probability of getting a correct response
* @param {number} options.nTrials - maximum number of trials
* @param {number} options.stopInterval - minimum [5%, 95%] confidence interval required for the loop to stop
* @param {module:data.QuestHandler.Method} options.method - the QUEST method
* @param {number} [options.beta=3.5] - steepness of the QUEST psychometric function
* @param {number} [options.delta=0.01] - fraction of trials with blind responses
* @param {number} [options.gamma=0.5] - fraction of trails that would generate a correct response when the threshold is infinitely small
* @param {number} [options.grain=0.01] - quantization of the internal table
* @param {string} options.name - name of the handler
* @param {boolean} [options.autoLog= false] - whether or not to log
*/
export class QuestHandler extends TrialHandler
{
/**
* @constructor
* @public
*/
constructor({
psychoJS,
varName,
startVal,
startValSd,
minVal,
maxVal,
pThreshold,
nTrials,
stopInterval,
method,
beta,
delta,
gamma,
grain,
name,
autoLog
} = {})
{
super({
psychoJS,
name,
autoLog,
method: TrialHandler.Method.SEQUENTIAL,
trialList: Array(nTrials),
nReps: 1
});
this._addAttribute("varName", varName);
this._addAttribute("startVal", startVal);
this._addAttribute("minVal", minVal, Number.MIN_VALUE);
this._addAttribute("maxVal", maxVal, Number.MAX_VALUE);
this._addAttribute("startValSd", startValSd);
this._addAttribute("pThreshold", pThreshold, 0.82);
this._addAttribute("nTrials", nTrials);
this._addAttribute("stopInterval", stopInterval, Number.MIN_VALUE);
this._addAttribute("beta", beta, 3.5);
this._addAttribute("delta", delta, 0.01);
this._addAttribute("gamma", gamma, 0.5);
this._addAttribute("grain", grain, 0.01);
this._addAttribute("method", method, QuestHandler.Method.QUANTILE);
// setup jsQuest:
this._setupJsQuest();
this._estimateQuestValue();
}
/**
* Setter for the method attribute.
*
* @param {mixed} method - the method value, PsychoPy-style values ("mean", "median",
* "quantile") are converted to their respective QuestHandler.Method values
* @param {boolean} log - whether or not to log the change of seed
*/
setMethod(method, log)
{
let methodMapping = {
"quantile": QuestHandler.Method.QUANTILE,
"mean": QuestHandler.Method.MEAN,
"mode": QuestHandler.Method.MODE
};
// If method is a key in methodMapping, convert method to corresponding value
if (methodMapping.hasOwnProperty(method))
{
method = methodMapping[method];
}
this._setAttribute("method", method, log);
}
/**
* Add a response and update the PDF.
*
* @name module:data.QuestHandler#addResponse
* @function
* @public
* @param{number} response - the response to the trial, must be either 0 (incorrect or
* non-detected) or 1 (correct or detected)
* @param{number | undefined} value - optional intensity / contrast / threshold
* @param{boolean} [doAddData = true] - whether or not to add the response as data to the
* experiment
* @returns {void}
*/
addResponse(response, value, doAddData = true)
{
// check that response is either 0 or 1:
if (response !== 0 &amp;&amp; response !== 1)
{
throw {
origin: "QuestHandler.addResponse",
context: "when adding a trial response",
error: `the response must be either 0 or 1, got: ${JSON.stringify(response)}`
};
}
if (doAddData)
{
this._psychoJS.experiment.addData(this._name + '.response', response);
}
// update the QUEST pdf:
if (typeof value !== "undefined")
{
this._jsQuest = jsQUEST.QuestUpdate(this._jsQuest, value, response);
}
else
{
this._jsQuest = jsQUEST.QuestUpdate(this._jsQuest, this._questValue, response);
}
if (!this._finished)
{
this.next();
// estimate the next value of the QUEST variable
// (and update the trial list and snapshots):
this._estimateQuestValue();
}
}
/**
* Simulate a response.
*
* @name module:data.QuestHandler#simulate
* @function
* @public
* @param{number} trueValue - the true, known value of the threshold / contrast / intensity
* @returns{number} the simulated response, 0 or 1
*/
simulate(trueValue)
{
const response = jsQUEST.QuestSimulate(this._jsQuest, this._questValue, trueValue);
// restrict to limits:
this._questValue = Math.max(this._minVal, Math.min(this._maxVal, this._questValue));
this._psychoJS.logger.debug(`simulated response: ${response}`);
return response;
}
/**
* Get the mean of the Quest posterior PDF.
*
* @name module:data.QuestHandler#mean
* @function
* @public
* @returns {number} the mean
*/
mean()
{
return jsQUEST.QuestMean(this._jsQuest);
}
/**
* Get the standard deviation of the Quest posterior PDF.
*
* @name module:data.QuestHandler#sd
* @function
* @public
* @returns {number} the standard deviation
*/
sd()
{
return jsQUEST.QuestSd(this._jsQuest);
}
/**
* Get the mode of the Quest posterior PDF.
*
* @name module:data.QuestHandler#mode
* @function
* @public
* @returns {number} the mode
*/
mode()
{
const [mode, pdf] = jsQUEST.QuestMode(this._jsQuest);
return mode;
}
/**
* Get the standard deviation of the Quest posterior PDF.
*
* @name module:data.QuestHandler#quantile
* @function
* @public
* @param{number} quantileOrder the quantile order
* @returns {number} the quantile
*/
quantile(quantileOrder)
{
return jsQUEST.QuestQuantile(this._jsQuest, quantileOrder);
}
/**
* Get the current value of the variable / contrast / threshold.
*
* @name module:data.QuestHandler#getQuestValue
* @function
* @public
* @returns {number} the current QUEST value for the variable / contrast / threshold
*/
getQuestValue()
{
return this._questValue;
}
/**
* Get an estimate of the 5%-95% confidence interval (CI).
*
* @name module:data.QuestHandler#confInterval
* @function
* @public
* @param{boolean} [getDifference=false] - if true, return the width of the CI instead of the CI
* @returns{number[] | number} the 5%-95% CI or the width of the CI
*/
confInterval(getDifference = false)
{
const CI = [
jsQUEST.QuestQuantile(this._jsQuest, 0.05),
jsQUEST.QuestQuantile(this._jsQuest, 0.95)
];
if (getDifference)
{
return Math.abs(CI[0] - CI[1]);
}
else
{
return CI;
}
}
/**
* Setup the JS Quest object.
*
* @name module:data.QuestHandler#_setupJsQuest
* @function
* @protected
* @returns {void}
*/
_setupJsQuest()
{
this._jsQuest = jsQUEST.QuestCreate(
this._startVal,
this._startValSd,
this._pThreshold,
this._beta,
this._delta,
this._gamma,
this._grain);
}
/**
* Estimate the next value of the QUEST variable, based on the current value
* and on the selected QUEST method.
*
* @name module:data.QuestHandler#_estimateQuestValue
* @function
* @protected
* @returns {void}
*/
_estimateQuestValue()
{
// estimate the value based on the chosen QUEST method:
if (this._method === QuestHandler.Method.QUANTILE)
{
this._questValue = jsQUEST.QuestQuantile(this._jsQuest);
}
else if (this._method === QuestHandler.Method.MEAN)
{
this._questValue = jsQUEST.QuestMean(this._jsQuest);
}
else if (this._method === QuestHandler.Method.MODE)
{
const [mode, pdf] = jsQUEST.QuestMode(this._jsQuest);
this._questValue = mode;
}
else
{
throw {
origin: "QuestHandler._estimateQuestValue",
context: "when estimating the next value of the QUEST variable",
error: `unknown method: ${this._method}, please use: mean, mode, or quantile`
};
}
this._psychoJS.logger.debug(`estimated value for QUEST variable ${this._varName}: ${this._questValue}`);
// check whether we should finish the trial:
if (this.thisN > 0 &amp;&amp; (this.nRemaining === 0 || this.confInterval(true) &lt; this._stopInterval))
{
this._finished = true;
// update the snapshots associated with the current trial in the trial list:
for (let t = 0; t &lt; this._snapshots.length - 1; ++t)
{
// the current trial is the last defined one:
if (typeof this._trialList[t + 1] === "undefined")
{
this._snapshots[t].finished = true;
break;
}
}
return;
}
// update the next undefined trial in the trial list, and the associated snapshot:
for (let t = 0; t &lt; this._trialList.length; ++t)
{
if (typeof this._trialList[t] === "undefined")
{
this._trialList[t] = { [this._varName]: this._questValue };
if (typeof this._snapshots[t] !== "undefined")
{
this._snapshots[t][this._varName] = this._questValue;
this._snapshots[t].trialAttributes.push(this._varName);
}
break;
}
}
}
}
/**
* QuestHandler method
*
* @enum {Symbol}
* @readonly
* @public
*/
QuestHandler.Method = {
/**
* Quantile threshold estimate.
*/
QUANTILE: Symbol.for("QUANTILE"),
/**
* Mean threshold estimate.
*/
MEAN: Symbol.for("MEAN"),
/**
* Mode threshold estimate.
*/
MODE: Symbol.for("MODE")
};
</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="FaceDetector_FaceDetector.html">FaceDetector</a></li><li><a href="module.data.MultiStairHandler.html">MultiStairHandler</a></li><li><a href="module.data.QuestHandler.html">QuestHandler</a></li><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.Keyboard.html">Keyboard</a></li><li><a href="module-core.KeyPress.html">KeyPress</a></li><li><a href="module-core.Logger.html">Logger</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.MultiStairHandler.html">MultiStairHandler</a></li><li><a href="module-data.QuestHandler.html">QuestHandler</a></li><li><a href="module-data.Shelf.html">Shelf</a></li><li><a href="module-data.TrialHandler.html">TrialHandler</a></li><li><a href="module-sound.AudioClip.html">AudioClip</a></li><li><a href="module-sound.AudioClipPlayer.html">AudioClipPlayer</a></li><li><a href="module-sound.Microphone.html">Microphone</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-sound.Transcriber.html">Transcriber</a></li><li><a href="module-sound.Transcript.html">Transcript</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.MixinBuilder.html">MixinBuilder</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.ButtonStim.html">ButtonStim</a></li><li><a href="module-visual.Camera.html">Camera</a></li><li><a href="module-visual.FaceDetector.html">FaceDetector</a></li><li><a href="module-visual.Form.html">Form</a></li><li><a href="module-visual.GratingStim.html">GratingStim</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.Polygon.html">Polygon</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.TextBox.html">TextBox</a></li><li><a href="module-visual.TextStim.html">TextStim</a></li><li><a href="module-visual.VisualStim.html">VisualStim</a></li></ul><h3>Interfaces</h3><ul><li><a href="module-sound.SoundPlayer.html">SoundPlayer</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>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.7</a> on Mon May 23 2022 12:29:28 GMT+0200 (Central European Summer Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>
View Git Blame Copy Permalink