Phase Locker Element

Summary ¶

	Phase Locker
Info
Category:	Signal Processing		AddIn:	Phase Locking
Creator:	OkazoLab		Scope:	Parent event
Owns Snippets:	Triggered		Usage:	Snippets

Properties ¶

Name	Description	Constraints	Type	On runtime change
Control
Title	Title of the element	Design Time..	String
Is Enabled	If set to false the element is completely omitted when the experiment is run	Design Time..	Boolean
Signal Source
Sampling Rate	Defines the sampling rate of the input signal in samples per second. This is crucial for accurate phase-locking	Design Time..	Int32
Input Channel	Defines the channel in the EventIDE signal pool that will provides data for the element	Design Time..	Int32
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.	Design Time..	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.	Design Time..	Double
Brain Wave Preset	Defines the preset ROI ranges for the most common brain rhymes	Design Time..	Int32
Frequency Range	Defines 'the frequency range of interest' for phase locking and PSD stats on the Session Statistics plot.	Normal..	clRange
Forecast Period	Defines a length of the forecasted (future) signal in periods of the central frequency in 'the frequency range of interest'	Design Time..	Double
NLF Iterations	Defines the maximal number of iterations in the non-linear fitting	Normal..	Int32
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	Normal..	Boolean
Session Stats Tick	Defines a tick interval for updating the session statistics plot	Normal..	String
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 ';')	Normal..	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.	Normal..	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.	Normal..	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."	Normal..	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.	Normal..	Double
Thresholds
Power Threshold	Defines the minimal threshold for a power of the dominant frequency that allows the phase prediction.	Normal..	Double
Residual Error Threshold	Defines the minimal threshold for the normalized residual error (MAE)	Normal..	Double
ACF Threshold	Defines the minimal threshold for the ACF error	Normal..	Double
Model Correlation Threshold	Defines the minimal threshold for the normalized phase fitting error	Normal..	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.	Normal..	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.	Normal..	Double
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.	Normal..	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	Normal..	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	Normal..	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	Normal..	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	Normal..	Double
Min Prediction Interval	Defines a minimal time interval (ms) between two consecutive predictions	Normal..	Double
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	Normal..	Boolean
Triggering Time	Returns a local event time (ms) of the last triggering.	Status..	clTime
Current Lock Phase	Returns the currently expected phase among all target phases	Status..	Double
XAML Dashboard	Returns a live XAML widget that can be used for online monitoring and parameter adjustments on the status screen	Normal..	UIElement

¶

Description ¶

Practical Use ¶

Configuring for the first use ¶

1. 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.
2. Browse to the element properties in the Properties panel.
3. Select the 'Input Signal' among those available in the current experiment.
4. Enter the actual sampling rate of the selected signal in the 'Sampling Rate' property.
5. Choose the target frequency range by defining the 'Frequency Range' property or select one of the presets via the 'Brain Wave Preset' property.
6. 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.
7. 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).
8. 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.
9. 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.
10. 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.
11. 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 ¶

1. 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.
2. 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.
   

Triggering stimulus presentation by 'Is Triggered' property ¶

1. Add 2 subevents to the parent event of the Phase Locker element and name them 'Wait' and 'Stimulus'.
2. 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.
3. Create a proxy variable for the 'Is Triggered' property of the Phase Locker element.
4. Use this proxy variable as a condition for the Wait -> Stimulus route, for instance, (IsTriggered==true).
5. Reset the IsTriggered proxy variable to 'false' in the After Onset snippet of the Wait event: IsTriggered=false;
6. 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 ¶