====== Event Onset ======

==== Overview ====
The **Event_Onset** command is used to detect and label an event when a specified signal crosses a defined threshold. This command allows users to analyze motion signals by specifying a threshold, direction of crossing, and optional baseline conditions. The event can be applied to individual signal components and constrained within a specified frame window or event range.

The command creates an event label at either the last minimum value before a threshold crossing, or at the last baseline threshold. THe closest event is set as the ONSET event. Some key details are as follows:
  * The threshold crossing is a fairly high value (or metric) that the user is confident is beyond the Event of interest.
  * The baseline crossing is a low threshold value (or metric) which is typically the point at which a velocity signal(for example) just starts moving.
  * The last local minimum before the threshold crossing (higher threshold).
  * The event from the baseline crossing and local minimum that is closest to the higher threshold crossing is set as the ONSET Event.
  * If multiple components are chosen (X Y and Z), the command will look for when any component passes the threshold and when any component reaches the baseline or a local minimum.

==== Pipeline Command ====
The command below is as seen in the Visual3D application.

<code>
Event_Onset
! /SIGNAL_TYPES=
! /SIGNAL_FOLDER=ORIGINAL
! /SIGNAL_NAMES=
/EVENT_NAME=
! /SELECT_X=TRUE
! /SELECT_Y=FALSE
! /SELECT_Z=FALSE
/THRESHOLD=0
! /THRESHOLD_INSTANCE=0
! /BASELINE=0
! /FRAME_OFFSET=0
! /FRAME_WINDOW=8
! /ASCENDING=FALSE
! /DESCENDING=FALSE
! /START_AT_EVENT=
! /END_AT_EVENT=
;
</code>

==== Command Parameters ====
The following table shows the command parameters and descriptions:

|**Parameter**   |**Description**|
|**!/SIGNAL_TYPES=**|Specifies the type of signal being analyzed (Analog, Link Model Based, etc.)|
|**!/SIGNAL_FOLDER=ORIGINAL**|The folder where the signal is stored.|
|**!/SIGNAL_NAMES=**|Defines the specific signal name within the selected type.|
|**/EVENT_NAME=**|The name of the new event created when the threshold is reached.|
|**!/SELECT_(X,Y,Z)=**|Determines which component of the signal should be evaluated. (TRUE/FALSE)|
|**/THRESHOLD=0**|Defines the threshold value that the signal must cross to trigger the event.|
|**!/THRESHOLD_INSTANCE=0**|Specifies which occurrence of the threshold crossing should be used.|
|**!/BASELINE=0**|A reference value; if the signal crosses this point before the local minimum, the event is placed at this frame.|
|**!/FRAME_OFFSET=0**|The number of frames to shift the event forward or backward after threshold detection.|
|**!/FRAME_WINDOW=8**|The required range of frames that must satisfy the threshold crossing condition.|
|**!/ASCENDING (/DESCENDING)=FALSE**|Determines whether the threshold is detected when the signal crosses upward or downward (TRUE/FALSE).|
|**!/START_AT_EVENT=**| Defines the event from which the search for the threshold begins.|
|**!/END_AT_EVENT=**|Defines the event where the search for the threshold stops.|

==== Dialog ====
The command can be edited in a text editor or in a dialog form. To edit in the dialog pop up form either click on the **Edit** button in the pipeline workshop or double-click on the pipeline command. The dialog is shown below.

{{:Event_Onset.jpg?350}}

==== Examples ==== 
The following examples will go through the use of the Event_Onset command in the Visual3D application.

=== Example 1 ===
This example identifies movement onset based on the speed of the hand. It detects the onset of hand movement (labeled as "ON") by looking for when the hand's speed exceeds 0.2m/s, but only during the time between a "GO" event and a maximum velocity event (VEL_MAX) event. It focuses on the upward crossing of the speed threshold.

<code>
Event_Onset
/Signal_Types=DERIVED
/Signal_Names=HANDSPEED
/Signal_Folder=PROCESSED
/Event_Name=ON
/Select_X=TRUE
/Select_Y=FALSE
/Select_Z=FALSE 
/THRESHOLD=0.2
/Threshold_Instance=0
/Baseline=0.05
/Frame_Window=8
/Frame_Offset=0
/Ascending=TRUE
/Descending=FALSE
/Start_At_Event=GO
/End_At_Event=VEL_MAX
;
</code>  

**Note**: Both the Threshold and Baseline parameter accept either a number or a METRIC

=== Example 2 ===
The following command is designed to automatically detect and label an event named "SCOTT2" when the Left_GRF (Left Ground Reaction Force) signal crosses a threshold of 25 Newtons. It's specifically looking for when the force is increasing (ascending) and goes above 25N.

<code>
Event_Onset
/SIGNAL_TYPES= LINK_MODEL_BASED
/SIGNAL_NAMES= Left_GRF
!/SIGNAL_FOLDER= ORIGINAL
/EVENT_NAME= SCOTT2
!/SELECT_X= TRUE
!/SELECT_Y= FALSE
!/SELECT_Z= FALSE
/THRESHOLD= 25
!/THRESHOLD_INSTANCE=0 
!/BASELINE= 0
!/FRAME_WINDOW= 8
/ASCENDING= TRUE
!/DESCENDING= FALSE
!/START_AT_EVENT=
!/END_AT_EVENT= 
; 
</code>

**Result:**

Visual3D will find when the signal crosses the threshold (25N) and look backwards in time (along the light blue) and find **EITHER**:
  - When the signal reaches the baseline of 0 N (this is indicated by the first instance of SCOTT2. 
  - When the signal reaches the local minima (this is indicated by the second instance of SCOTT2.

{{:EventOnset_Scott2_Graph.jpg?}}


==== Notes ====
  * The /Ascending and /Descending parameters determine whether the event is placed at an upward or downward threshold crossing.
  * The /Frame_Offset can be used to shift the event placement after threshold detection.
  * The /Baseline is useful when detecting minima or maxima, ensuring the event is placed correctly.