====== 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 ====

<code>
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
</code>
{{:EventThresholdDialog_v5.jpg}}|


==== THRESHOLD Parameter ====

The Threshold parameter can be:

**a number**
**a PROCESSED METRIC**
**an expression**

For example:

**a number**\\
/Threshold= 1

**a PROCESSED METRIC**\\
If a METRIC value is stored in the PROCESSED folder, the Event_Threshold command will recognize and use the signal based only on the signal name.\\
Given a METRIC signal named THRESH stored in the PROCESSED folder, you can specify the parameter as:\\
/Threshold= THRESH

**an expression**\\
It is also possible to use expressions, but when using expressions you must use the full signal name.

Given a METRIC signals THRESH that is stored in a folder labeled TEST\\
/Threshold= METRIC::TEST::THRESH

But you can also elaborate this expression, such as\\
/Threshold= 1.0 + 0.2 * METRIC::TEST::THRESH

==== Example ====

**Create events using the Event_Threshold command**: **FP3_Y and FP3_Y_ENSURE**

The event **FP3_Y_ENSURE** will use the Ensure Window After option on the dialog box.

**Make sure to:**\\
1) Import the SIGNAL_TYPE/FOLDER or enter these parameters manually into the text editor\\
2) Only one signal component may be specified at a time\\
3) Select label on Ascent/Descent - if neither are selected no events will be created\\

<code>
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
;
</code>
{{:EventThreshold_FP3_Y.jpg}}|

<code>
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
;
</code>
{{: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.