Phase Locker Element

Modified on 2024/11/19 04:23 by Administrator Categorized as Elements, Signal Processing
<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=Phase Locker
| category=Signal Processing
| icon=[image|Element Icon|{UP(Phase-Locker-Element)}Phase-Locker-Element-Icon.png]
| author= OkazoLab
| addin= Phase Locking
| scope= Parent event
| usage= Snippets
| ownsnippets=  Triggered
}
== Properties ==
{|
|-
! Name
! Description                              
! Constraints
! Type
! On<br/>runtime<br/>change
|-
| colspan="5" bgcolor="#AADDDDD" | Control
|-
| Title        
| Title of the element        
| {s:atDesign}        
| String        
|  
|-
| Is Enabled        
| If set to false the element is completely omitted when the experiment is run        
| {s:atDesign}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Signal Source
|-
| Sampling Rate        
| Defines the sampling rate of the input signal in samples per second. This is crucial for accurate phase-locking        
| {s:atDesign}        
| Int32        
|  
|-
| Input Channel        
| Defines the channel in the EventIDE signal pool that will provides data for the element        
| {s:atDesign}        
| Int32        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Signal Modeling
|-
| Analysis Window Length        
| Defines the time length of the analysis moving window of the input signal, in seconds. This window is used to visualization and evaluation of phase-locking results.        
| {s:atDesign}        
| Double        
|  
|-
| Model Period        
| Defines the length of the model segment in periods of the central frequency in 'the frequency range of interest'. The model segment is aligned to the right-most part of the analysis window.        
| {s:atDesign}        
| Double        
|  
|-
| Brain Wave Preset        
| Defines the preset ROI ranges for the most common brain rhymes        
| {s:atDesign}        
| Int32        
|  
|-
| Frequency Range        
| Defines 'the frequency range of interest' for phase locking and PSD stats on the Session Statistics plot.        
| {s:atNormal}        
| clRange        
|  
|-
| Forecast Period        
| Defines a length of the forecasted (future) signal in periods of the central frequency in 'the frequency range of interest'        
| {s:atDesign}        
| Double        
|  
|-
| NLF Iterations        
| Defines the maximal number of iterations in the non-linear fitting        
| {s:atNormal}        
| Int32        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Prediction Statistics
|-
| Store model/signal samples        
| Defines whether the samples of the input signal and the fitted models are stored in the prediction list data file        
| {s:atNormal}        
| Boolean        
|  
|-
| Session Stats Tick        
| Defines a tick interval for updating the session statistics plot        
| {s:atNormal}        
| String        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Phase Locking
|-
| Target Phase        
| Defines sine phases (in degrees) that need to be predicted in the forecasted signal. To define more than one phase, enter values with delimiters (' ','|' or ';')        
| {s:atNormal}        
| String        
|  
|-
| Is Presenting        
| Defines whether the stimulus presentation mode is enabled. In that presentation mode, the element gets triggered at the time of the target phase and calls the triggered snippet. In turn, the latter can be used to present a stimulus or to run user events.        
| {s:atNormal}        
| Boolean        
|  
|-
| Presentation Mode        
| Defines a stimulus sequence when the stimulus presentation mode is enabled. If the 'Single presentation' is selected, the stimulus presentation mode is automatically switched off after the first presentation. If 'Sequential presentation' is selected, the stimuli are presented until the stimulus presentation mode is turned off manually.        
| {s:atNormal}        
| Int32        
|  
|-
| Prehold Number        
| Defines the number of prehold presentations (within the max prehold interval) required before the element is triggered for a real phase-locked stimulus presentation. Using this property may help in preventing stimulus presentations on incidental oscillations."        
| {s:atNormal}        
| Int32        
|  
|-
| Max Prehold Interval        
| Defines the maximum time interval (in milliseconds) between two potential presentations, counted in relation to the Prehold Number. If the value is zero, the property is ignored. Otherwise, the Prehold counter resets if the time interval exceeds the specified property value.        
| {s:atNormal}        
| Double        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Thresholds
|-
| Power Threshold        
| Defines the minimal threshold for a power of the dominant frequency that allows the phase prediction.        
| {s:atNormal}        
| Double        
|  
|-
| Residual Error Threshold        
| Defines the minimal threshold for the normalized residual error (MAE)        
| {s:atNormal}        
| Double        
|  
|-
| ACF Threshold        
| Defines the minimal threshold for the ACF error        
| {s:atNormal}        
| Double        
|  
|-
| Model Correlation Threshold        
| Defines the minimal threshold for the normalized phase fitting error        
| {s:atNormal}        
| Double        
|  
|-
| Minimal Amplitude Threshold        
| Defines the minimal allowed peak amplitude for the fitting segment. Since the algorithm works with a non-normalized input signal, the threshold value must be found empirically. If the zero value is set, this threshold is ignored.        
| {s:atNormal}        
| Double        
|  
|-
| Maximal Amplitude Threshold        
| Defines the maximal allowed peak amplitude for the fitting segment. Since the the algorithm works with a non-normalized input signal, the threshold value must be found empirically. If the zero value is set, this threshold is ignored.        
| {s:atNormal}        
| Double        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Crunch Time
|-
| Hardware Lag        
| Defines a time lag in signal acquisition. When the lag is measured empirically the value should be defined manually. When auto correction is enabled, the lag is estimated automatically.        
| {s:atNormal}        
| Double        
|  
|-
| Auto Crunch Times        
| Defines whether the target phase is automatically shifted in order to compensate the hardware lag. If the mode is on the hardware lag does not included in the crunch time        
| {s:atNormal}        
| Boolean        
|  
|-
| Smart Phase Mode        
| Defines whether the target phase is automatically shifted in order to compensate the hardware lag. If the mode is on the hardware lag does not included in the crunch time        
| {s:atNormal}        
| Boolean        
|  
|-
| Min Crunch Time        
| Defines the lower bound for a period of future time (ms), in which prediction of the target phase can be made. If the target phase is expected earlier in time, the prediction is dismissed. The min crunch time must be less than the max crunch time and greater than the hardware lag plus the analysis time        
| {s:atNormal}        
| Double        
|  
|-
| Max Crunch Time        
| Defines the upper bound for a period of future time (ms), in which prediction of the target phase can be made. If the target phase is expected later in time, the prediction is dismissed. The max crunch time must be greater than he min crunch time and less than the length of the modeled signal        
| {s:atNormal}        
| Double        
|  
|-
| Min Prediction Interval        
| Defines a minimal time interval (ms) between two consecutive predictions        
| {s:atNormal}        
| Double        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Runtime Status
|-
| Is Triggered        
| Indicates whether the elements signal the predicted phase occurrence in real-time. This status variable can be used for accurate phase-locked stimulus presentation        
| {s:atNormal}        
| Boolean        
|  
|-
| Triggering Time        
| Returns a local event time (ms) of the last triggering.        
| {s:atStatus}        
| clTime        
|  
|-
| Current Lock Phase        
| Returns the currently expected phase among all target phases        
| {s:atStatus}        
| Double        
|  
|-
| XAML Dashboard        
| Returns a live XAML widget that can be used for online monitoring and parameter adjustments on the status screen        
| {s:atNormal}        
| UIElement       
|  
|-            
|}
== ==
</div>
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
The Phase Locker element is a core component of [https://www.okazolab.com/phase-locked|the phase-locked stimulus presentation] in EventIDE. The element runs an analys of online signal and triggers when a selected phase of signal ossilation (in desired frequency range) is met. The triggering of the element can be then used for an immediate presentation of stimulus or triggering other custom functions in an experiment.

{TOC}
== Description ==

== Practical Use ==

=== Configuring for the first use ===

# Add the element to an event that incorporates both signal processing and stimulus presentation. Such an event may have subevents that denote different stages of the stimulation procedure.
# Browse to the element properties in the Properties panel.
# Select the 'Input Signal' among those available in the current experiment.
# Enter the actual sampling rate of the selected signal in the 'Sampling Rate' property.
# Choose the target frequency range by defining the 'Frequency Range' property or select one of the presets via the 'Brain Wave Preset' property.
# Enter the total length (in seconds) of a moving analysis window for signal visualization via the 'Analysis Window Length' property. The recommended value is about 4-10 periods of the central target oscillation. For instance, a 4-second window for the delta oscillations in the 0.5 - 1 Hz target range. There is no length restriction for the analysis window, apart from performance considerations.
# Define the length of the right-most 'modeling' segment on the analysis window in periods of the central target oscillation. The signal in the modeling segment is used to build a future continuation of the current signal. The recommended period values are between 0.9 (faster detection) and 1.5 (more accurate detection).
# Define the target phase (in degrees of the sine wave) for stimulus presentation via the 'Target Phase' property. If you plan to hit multiple phases, enter them with a '|' separator, for example, 90|180.
# Enter the total measured latency (ms) of your signal recording into the 'Hardware Lag' property. The latency is the time needed to deliver the signal from hardware to EventIDE.
# If you have a secondary monitor and use the EventIDE status screen at runtime, you can add the Phase Locker dashboard widget there via the status screen designer or XAML. The dashboard widget visualizes all stats of the phase-locking processing and allows changing of related parameters at runtime.
# In most cases, other properties of the Phase Locker element can be used with the default values.

=== Configuring stimulus presentation with the Phase Locker element ===

# If you want to present a stimulus sequence locked to every target phase in a signal, set the 'Presentation Mode' property to 'Sequential Presentations'. If you plan to present a single stimulus at the first occurrence of the target phase, set 'Presentation Mode' to 'Single Presentation'. The single presentation mode can be resumed manually after each stimulus presentation.
# Enable or disable the stimulus presentation with the 'Is Presenting' property. This property can be controlled at runtime either by scripts or by the dashboard widget of the element.

Phase locker element does not run stimulus presentaion by itself, but here are two easy ways for linked the element to trigger any stimulus presentation in EventIDE.

==== Triggering stimulus presentation by 'Is Triggered' property ====

# Add 2 subevents to the parent event of the Phase Locker element and name them 'Wait' and 'Stimulus'.
# Add 2 event routes: the conditional route from the Wait event to the Stimulus event and a time route back from the Stimulus event to the Wait event.
# Create a proxy variable for the 'Is Triggered' property of the Phase Locker element.
# Use this proxy variable as a condition for the Wait -> Stimulus route, for instance, (IsTriggered==true).
# Reset the IsTriggered proxy variable to 'false' in the After Onset snippet of the Wait event: IsTriggered=false;
# Design your stimulus presentation in the Stimulus event. For example, you can add the Renderer element for a visual stimulus, the Wave Player for an audio stimulus, or a COM port element for sending a command to external hardware.

==== Triggering stimulus presentation by the Triggered snippet ====

If you need more customization of stimulus presentation, you can use the Triggered snippet of the Phase Locker element to write your custom script there. The script will be invoked exactly at the time of the target phase, thus allowing you to run any stimulus presentation that you programmed. The script can read the current element properties, for example, 'Current Lock Phase' value when multiple target phases are used.
Meta Keywords:
Meta Description:
Change Comment:
EventIDE Wiki

Navigation¶

Phase Locker Element
