====== 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. ==== 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 nema. 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\\ \\ |\\ 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.