Staircase Method Element

Modified on 2018/08/03 05:03 by Administrator Categorized as Elements, Randomization
<div style="margin-right: 10px; margin-left: 16px; margin-bottom:10px; float: right; width: 500px; overflow: hidden; height: auto; padding: 0px; background: #fafafa; background: -webkit-gradient(linear, left top, left bottom, from(#fbfbfb), to(#fafafa));background: -moz-linear-gradient(top, #fbfbfb, #fafafa);border: 1px dashed #ddd;box-shadow: 0 0 0 3px #fff, 0 0 0 5px #ddd, 0 0 0 10px #fff, 0 0 2px 10px #eee;">
== Summary ==
{s:Element Info Panel
| title=Staircase Method
| category=Randomization
| icon=[image|Element Icon|{UP(Staircase-Method-Element)}Staircase-Method-Element-Icon.png]
| author= OkazoLab
| addin= Psychophysics
| scope= Experiment
| usage= Snippets
| ownsnippets= None
}
== Properties ==
{|
|-
! Name
! Description                              
! Constraints
! Type
! On<br/>runtime<br/>change
|-
| colspan="5" bgcolor="#AADDDDD" | Staircase Settings
|-
| Desired Correct Rate        
| Defines the fixed participant's performance level for the estimated threshold, in percentages. The staircase steps on correct and wrong responses will be different if this value is not equal change level-50%. The valid input range is between 0 and 100.        
| {s:atNormal}        
| Double        
|  
|-
| Initial Intensity        
| Defines the initial value of stimulus intensity. If the value is changed at runtime, the staircase aborts the current estimate and resets all parameters.        
| {s:atNormal}        
| Double        
|  
|-
| Forward Step        
| Defines the change in stimulus intensity for the correct response. A sign of the value defines the staircase direction relative to the initial value. The reverse step size for the wrong answers is calculated automatically, based on the Staircase Step and the value of Desired Correct Rate property and should remain fixed during the estimation procedure.        
| {s:atNormal}        
| Double        
|  
|-
| Inverse Step        
| Indicates a size of the change in stimulus intensity for the wrong response. The value is calculated automatically, based on the Desired Correct Rate and Staircase Step properties.        
| {s:atStatus}        
| Double        
|  
|-
| Reversal Number        
| Defines the total number of reversals, or staircase length, required to complete the threshold estimation        
| {s:atNormal}        
| Int32        
|  
|-
| Ignorable Reversals        
| Defines a number of the initial reversals that are excluded from the threshold estimation (but still be counted in the staircase length)         
| {s:atNormal}        
| Int32        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Staircase Plotting
|-
| Rendering Size        
| Defines the size of the generated XAML staircase plot in pixels. The plot is automatically stretched on rendering, but a larger rendering size improves the chart quality with some cost in performance. The rendering size is also used as the resulting image resolution, when the chart is saved into a file.        
| {s:atDesign}        
| clSize        
|  
|-
| Plot Title        
|         
| {s:atNormal}        
| String        
|  
|-
| Show Subtitle        
| Defines whether the staircase statistics is shown in the plot subtitle        
| {s:atNormal}        
| Boolean        
|  
|-
| Font Size        
| Defines the font size for plot labels        
| {s:atNormal}        
| Double        
|  
|-
| Show Axis Bands        
| Defines whether the axis bands are shown on the plot area        
| {s:atNormal}        
| Boolean        
|  
|-
| Confidence Interval        
| Defines a type of the confidence intervals shown on the XAML staircase plot        
| {s:atDesign}        
| enStar..        
|  
|-
| XAML Staircase Plot        
| Returns a live XAML control that can be used for direct binding to the Content property of the XAML ContentControl element, e.g. <ContentControl Content='{Binding OnlineChart}'/> ContentControl with a generated staircase plot can be added to the status screen or to the XAML Layout element.        
| {s:atNormal}        
| UIElem..        
|  
|-
| Save Plot Now        
| Use this runtime command whenever you want to save a screenshot of the generated chart. To run the command, assign a string with a full file path and name to this property in a code snippet. The screenshot will be saved into the target file after the end of the snippet call. The format of the image file is defined by the extension of the file name, e.g. .bmp, .png or .jpg        
| {s:atRuntimeAction}        
| String        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Runtime Control
|-
| Add Response Now        
| Assigning a new value to this property in code snippets adds a single trial outcome to the staircase estimator. The value should be either boolean or integer: true/1 for the correct response and false/0 for the wrong response.        
| {s:atNormal}        
| Object        
|  
|-
| New Intensity        
| Returns a value for the stimulus intensity in the next trial as suggested by the staircase estimator. The value is updated after adding responses to the staircase estimator.        
| {s:atStatus}        
| Double        
|  
|-
| Reset Staircase Now        
| Runtime command that resets the current staircase and start a new estimator        
| {s:atRuntimeAction}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Runtime Results
|-
| Estimated Threshold        
| The current estimate of participant's threshold        
| {s:atStatus}        
| Double        
|  
|-
| Estimated Threshold SD        
| The current estimate of participant's threshold        
| {s:atStatus}        
| Double        
|  
|-
| Estimated Threshold SE        
| The current estimate of participant's threshold        
| {s:atStatus}        
| Double        
|  
|-
| Actual Correct Rate        
| Indicates the real correct rate calculated over all participant's responses, in percentages        
| {s:atStatus}        
| Double        
|  
|-
| Is Completed        
| Indicates whether the estimation of the threshold is completed - the total number of reversal is reached        
| {s:atStatus}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Staircase Data
|-
| Response Count        
| Indicates the number of the collected responses in the current staircase        
| {s:atStatus}        
| Int32        
|  
|-
| All Responses        
| Returns a boolean array of the collected responses in the current staircase         
| {s:atStatus}        
| Boolea..        
|  
|-
| Reversal Count        
| Indicates the number of the observed reversals in the current staircase (including the ignorable reversals)        
| {s:atStatus}        
| Int32        
|  
|-
| Staircase Points        
| Returns a double array of all intensity values in the current staircase. The array values are time-ordered and the value with the zero index corresponds to the initial intensity.        
| {s:atStatus}        
| Double..        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Control
|-
| Is Enabled        
| If set to false the element is completely omitted when the experiment is run        
| {s:atDesign}        
| Boolean        
|  
|-
| Title        
| Title of the element        
| {s:atDesign}        
| String        
|  
|-            
|}
== ==
</div>
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
'''Staircase Method Element''' allows an easy implementation of the weighted up/down staircase method with the fixed predefined performance rate (Kaernbach, 1991). The element collects various statistics and provides a dynamic staircase plot, which can be monitored on the status screen.<br><br>
{TOC}

== Description ==

Staircase element assists in implementing the single staircase method that efficiently estimates participant's detection threshold in regards to stimulus intensity (e.g. contrast or duration). The element continuously calculates adjustments for stimulus intensity on the basis of participant's consecutive responses. In addition, the element estimates the threshold of the given participant, collects various statistics and even generates the real-time staircase plot for the status screen.
In general, element's staircase algorithm resembles the classical staircase procedure introduced by von Békésy (1947). More particularly, the current algorithm is a replica of the weighted up/down staircase method with the fixed performance rate (Kaernbach, 1991).
The element implements a single staircase. If multiple staircases, interleaved or not, are required by an experimental paradigm, several Staircase elements can be used in parallel.
As it is shown below, only a new lines of user code are required to make use of Staircase Method element in any experiment.

== Snapshots ==
{|
| [imageleft|Example of the staircase plot on Status Screen <br/>|{UP(Staircase-Method-Element)}StaircasePlotsm.png|{UP(Staircase-Method-Element)}StaircasePlot.png]
|}

== Practical Use ==
=== Creating a staircase ===
'''Design time'''
# Add Staircase element to any of experiment's event. The event choice is not important for elements, like Staircase Method, working in the global scope of the experiment.
# Set a value of Initial Intensity property of the element. The numerical value should correspond the initial level of stimulus intensity that can be easily detected. For example, the number can be related to the opacity of a picture, or to duration of an audio.
# Set a value of Staircase Step property. The signed value denotes an adjustment of the stimulus intensity when the correct response is given by a participant. The adjustment on the wrong response is calculated by the element automatically as suggested by the weighted method. Smaller step value may lead to more accurate but slower staircase convergence.
# Set a percentage value of Performance Level property. The staircase procedure will be automatically adapted to keep participant's performance on the given fixed level. Thus, the staircase results will always show participant's detection threshold on the given performance level, e.g for 80% of detection rate. The chance level corresponds to the value 50.
# Set a value of Reversal Number property to define a total number of reversals necessary to complete the staircase procedure. Reaching the maximal reversal number does not stop the staircase procedure, the element simply signals this moment by setting true to its Is Completed property, which, in turn, can be used to control the experiment flow logic.
# Set a value of Ignorable Reversal greater than zero, if it's necessary to exclude several initial reversals from the threshold estimation, e.g. to avoid occasional outliers before convergence of the staircase close to the real threshold level.
# Create proxy variables for AddResponse and Next Intensity properties of the element. The first proxy will be used to add participant's responses to the staircase whereas the second for the adjusting stimulus intensity.
# Create proxy variables for the selected properties of Runtime Results category. The proxies will allow to monitor staircase statistics on the Status Screen and save results to Report.
'''Runtime'''
# In order to add a single participant response to the staircase, the trial outcome has to be added via AddResponse proxy (usually, at the end of a trial):
@@ csharp
if (Response==1)
AddResponse=true;
else
AddResponse=false;
@@
Integer values can be assigned to AddReponse proxy as well:
@@ csharp
AddResponse=Response; /// the Response here is an integer variable, which is equal 1 or 0 depending on the trial outcome
@@
#Adjust the intensity of the stimulus with Next Intensity value. A new value is calculated each time after adding a participant response (via AddResponse). At the start of the staircase Next Intensity is equal to Initial Intensity
@@ csharp
RendererOpacity=NextIntensity; /// adjusts the opacity of the visual stimulus
@@
or,
@@ csharp
EventDuration=Convert.ToUInt64(NextIntensity); /// adjusts duration of the stimulus presentation
@@
# After completion of the current staircase, it can be reset and used again in a new sequence of trials. Use the following code:
@@ csharp
ResetStaircase=true; /// ResetStaircase is a proxy variable linked to element's property of the same name.
@@
# The overall staircase progress (changes on the stimulus intensity over time) can be written to Report with the following code:
@@ csharp
Report="Stairscase of the stimulus intensity:\r\n";
for (int i=0;i<StaircasePoints.Length;i++)
Report=Report+StaircasePoints[i]+";"; /// where StaircasePoint is a proxy variable linked to element's property of the same name.
@@
# The graphical representation of the staircase progress can be monitored on the status screen with Staircase Plot property. The following code for Status Screen shows XAML binding to a proxy linked with the Staircase Plot property:
@@ xml
<Image Source="{Binding StaircasePlot}"/>
@@

== Notes ==
Adding participant's response to the staircase and adjusting the stimulus intensity with the next value MUST NOT be done in the same code snippet (the element estimates a new intensity after completion of the snippet where a new response is added). Instead, use separate consequent snippets in the experiment flow for these two actions. The example of the incorrect code is below:

@@ csharp
/// Incorrect use of the staircase !!!
AddResponse=Response;
EventDuration=Convert.ToUInt64(NextIntensity); /// Next Intensity is not updated yet
@@
== Demos ==
Demo experiment that shows an use of the StaircaseMethod can be found in: \Demos\Elements\Psychophisical_Methods\Staircase_Element_Demo.eve
Meta Keywords: EventIDE, Okazolab, staircase element, staircase method, staircase plot, weighted up/down staircase method
Meta Description:
Change Comment:
EventIDE Wiki

Navigation¶

Staircase Method Element
