====== Event Threshold ======
\\
**Place an event label at the frame where a signal crosses a specified value. The event is created at the frame satisfying the criteria.**
**This is a complicated command because there are so many options.**
\\
==== Command Syntax ====
|\\ Event_Threshold\\ /RESULT_EVENT_NAME= The name to be given to the threshold event\\ ! /Signal_Types= The type of signal to be evaluated\\ ! /SIGNAL_NAMES= The name of the signal to be evaluated\\ ! /Signal_Folder= The name of the signal folder\\ ! /SIGNAL_COMPONENTS= Use these components of the signal (May also be\\ modified using Select_X, Select_Y, Select_Z parameters)\\ ! /FRAME_OFFSET= The frame offset from the threshold crossing where \\ the event label is to be placed\\ ! /TIME_OFFSET= The time offset from the threshold crossing where the\\ event label is to be placed\\ ! /EVENT_SEQUENCE= A sequence of events to perform the command within\\ (for example: RHS+RHS)\\ ! /EXCLUDE_EVENTS= An that falls within an EVENT_SEQUENCE event may be\\ specified to exclude a sequence from the calculations\\ ! /EVENT_SEQUENCE_INSTANCE= Instance of event sequence \\ ! /EVENT_SUBSEQUENCE=A subsequence of events to perform the command\\ within (for example: LTO+LHS)\\ ! /SUBSEQUENCE_EXCLUDE_EVENTS=An event that falls within an\\ EVENT_SUBSEQUENCE may be specified to exclude a subsequence from the\\ calculations\\ ! /EVENT_SUBSEQUENCE_INSTANCE= Instance of event subsequence \\ ! /EVENT_INSTANCE= There may be several instances of an event crossing\\ satisfying the criteria. A value of 0 results in all crossing being assigned a\\ label. A positive number indicates the event (in sequence) to select. A \\ negative number indicates the event starting from the last event and \\ progressing to the first event.\\ ! /SELECT_X= (True or False)Use this component of the signal\\ ! /SELECT_Y= (True or False)Use this component of the signal\\ ! /SELECT_Z= (True or False)Use this component of the signal\\ ! /SELECT_RESIDUAL= (True or False)Use this component of the signal\\ ! /START_AT_EVENT= The search begins from the start event\\ ! /END_AT_EVENT= The search ends at the end event\\ ! /THRESHOLD= The value after which the event label is to be placed\\ ! /ON_ASCENT= (True or False) Determine the threshold when the signal\\ is passing up through the threshold\\ ! /ON_DESCENT= (True or False) Determine the threshold when the signal \\ is passing down through the threshold\\ ! /Frame_Window= The range of frames of data that must satisfy the \\ threshold crossing. Used by the "Ensure" variable\\ ! /ENSURE_FRAMES_BEFORE= (True or False)Radius frames of data before\\ crossing must lie on the same side of the threshold\\ ! /ENSURE_FRAMES_AFTER= (True or False)Radius frames of data after\\ crossing must lie on the same side of the threshold\\
| {{:EventThresholdDialog_v5.jpg}}|
=== Version 4 ===
{{:EventThresholdDialog.jpg}}
|**Event_Threshold** | |
|**/[[Visual3D:Documentation:Pipeline:General_Information:Signal_Types|Signal_Types]]=** |The type of signal to be evaluated |
|**/Signal_Names=** |The name of the signal to be evaluated |
|**/[[Visual3D:Documentation:Pipeline:General_Information:Signal_Folder|Signal_Folder]]=**|The name of the signal folder |
|**/Event_Name=** |The name to be given to the threshold event |
|**/Select_X=** |(True or False)Use this component of the signal |
|**/Select_Y=** |(True or False)Use this component of the signal |
|**/Select_Z=** |(True or False)Use this component of the signal |
|**/Threshold=** |The value after which the event label is to be placed |
|**/[[Visual3D:Documentation:Pipeline:General_Information:Frame_Window|Frame_Window]]=** |The range of frames of data that must satisfy the threshold crossing. Used by the "Ensure" variable |
|**/Frame_Offset=** |The frame offset from the threshold crossing where the event label is to be placed |
|**/Ascending=** |(True or False) Determine the threshold when the signal is passing up through the threshold |
|**/Descending=** |(True or False) Determine the threshold when the signal is passing down through the threshold |
|**/Ensure_Range_Frames_Before_Threshold_Crossing=** |(True or False)Radius frames of data before crossing must lie on the same side of the threshold |
|**/Ensure_Range_Frames_After_Threshold_Crossing=** |(True or False)Radius frames of data after crossing must lie on the same side of the threshold |
|**/Start_At_Event=** |The search begins from the start event |
|**/End_At_Event=** |The search ends at the end event |
|**/Event_Instance=** |There may be several instances of an event crossing satisfying the criteria. A value of 0 results in all crossing being assigned a label. A positive number indicates the event (in sequence) to select. A negative number indicates the event starting from the last event and progressing to the first event.|
----
==== Ensure Range Parameter ====
For example, consider the following signal from which an Event should be created when the signal crosses above the threshold (e.g. Ascending):
{{:Thresholdexamplesignal.gif}}
There are many options to this command because there are many possible choices for the most appropriate event.
\\ Event_Threshold\\ /RESULT_EVENT_NAME= FP3_Y\\ /SIGNAL_TYPES= FORCE\\ /SIGNAL_NAMES= FP3\\ ! /SIGNAL_FOLDER= ORIGINAL\\ /SIGNAL_COMPONENTS= Y\\ ! /FRAME_OFFSET= 0\\ ! /TIME_OFFSET= \\ ! /EVENT_SEQUENCE= \\ ! /EXCLUDE_EVENTS= \\ ! /EVENT_SEQUENCE_INSTANCE= 0\\ ! /EVENT_SUBSEQUENCE= \\ ! /SUBSEQUENCE_EXCLUDE_EVENTS= \\ ! /EVENT_SUBSEQUENCE_INSTANCE= 0\\ ! /EVENT_INSTANCE= 0\\ ! /SELECT_X= \\ ! /SELECT_Y= \\ ! /SELECT_Z= \\ ! /SELECT_RESIDUAL= \\ ! /START_AT_EVENT= \\ ! /END_AT_EVENT= \\ /THRESHOLD= 0.05\\ /ON_ASCENT= TRUE\\ /ON_DESCENT= FALSE\\ /FRAME_WINDOW= 25\\ /ENSURE_FRAMES_BEFORE= FALSE\\ /ENSURE_FRAMES_AFTER= FALSE\\ ; \\
| {{:EventThreshold_FP3_Y.jpg}}|
\\
|\\ Event_Threshold \\ /RESULT_EVENT_NAME= FP3_Y_ENSURE\\ /SIGNAL_TYPES= FORCE\\ /SIGNAL_NAMES= FP3\\ ! /SIGNAL_FOLDER= ORIGINAL\\ /SIGNAL_COMPONENTS= Y\\ ! /FRAME_OFFSET= 0\\ ! /TIME_OFFSET= \\ ! /EVENT_SEQUENCE= \\ ! /EXCLUDE_EVENTS= \\ ! /EVENT_SEQUENCE_INSTANCE= 0\\ ! /EVENT_SUBSEQUENCE= \\ ! /SUBSEQUENCE_EXCLUDE_EVENTS= \\ ! /EVENT_SUBSEQUENCE_INSTANCE= 0\\ ! /EVENT_INSTANCE= 0\\ ! /SELECT_X= \\ ! /SELECT_Y= \\ ! /SELECT_Z= \\ ! /SELECT_RESIDUAL= \\ ! /START_AT_EVENT= \\ ! /END_AT_EVENT= \\ /THRESHOLD= 0.05\\ /ON_ASCENT= TRUE\\ /ON_DESCENT= FALSE\\ /FRAME_WINDOW= 25\\ /ENSURE_FRAMES_BEFORE= FALSE\\ /ENSURE_FRAMES_AFTER= TRUE\\ ; \\
| {{:EventThreshold_FP3_Y_Ensure.jpg}}|
\\
\\
\\
=== Example - Result ===
\\
|Three events should be created:\\ 2 Instances of **FP3_Y** -\\ \\ The FP3_Y signal crosses the threshold (0.05) two times during the trial\\ \\ 1 Instance of **FP3_Y_ENSURE** -\\ \\ The FP3_Y signal crosses the threshold (0.05) and stays above the threshold for the frame window (25) one time during the trial |{{:EventThreshold_FP3_Y_Ensure_Graph.jpg}} |
==== Visual3D Versions supporting Subject Prefixes ====
When defining events for subjects that use a prefix to define the data belonging to that subject, event labels will also have the prefix of the subject the events belong to.
NOTE: When using events in a command, the commands will iterate across subjects contained in the current workspace. As such, events and sequences listed as command parameters should NOT contain a prefix. As each subject is processed, the event range/sequence specified will automatically use the specific events prefixed for each subject as they are processed.