.. _auto_curves_sign_change_stats:

*DETECT SIGN CHANGES AND RETURN THE STATS AROUND THAT POINT*
============================================================

Scans one or more time-history curves for the first sign change (positive-to-negative or negative-to-positive) and returns a statistics dataset describing the signal behaviour in a configurable pre- and post-switch time window around that crossing point. Use this worker to characterise transient events such as force reversals, velocity zero-crossings, or current direction changes.

When to use
-----------

Classification: **process**.

Tagged: ``curve_analysis``, ``fluctuation``, ``sign_change``, ``statistics``, ``time_window``, ``transient``, ``zero_crossing``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - Curves
     - curves
     - vector
     - —
     - 
     - One or more time-history curves (X-Y pairs) to be scanned for the sign-change event; accepts multiple curve objects.
   * - Switch Type
     - switchtype
     - list
     - positive_to_negative
     - 
     - Direction of the sign change to detect: 'positive_to_negative' (default) or 'negative_to_positive'; leave default when looking for a falling zero-crossing.
   * - Pre-switch Time Window
     - pre-switchtime_window
     - scalar
     - 600
     - 
     - Duration of the time window before the detected sign-change point over which statistics are computed; expressed in the same time units as the curve X-axis (default: 600).
   * - Post-switch Time Window
     - post-switchtime_window
     - scalar
     - 1200
     - 
     - Duration of the time window after the detected sign-change point over which statistics are computed; can be supplied as an absolute value or as a percentage of the pre-switch window (default: 1200).
   * - Fluctuation Time Window
     - fluctuationtimewindowinpercentage
     - scalar
     - 2%
     - 
     - Tolerance window, as a percentage of the pre-switch window size, within which minor signal fluctuations around zero are ignored so that noise does not trigger a false crossing detection (default: 2%).

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - curves_sign_change_stats_output_1
     - curves_sign_change_stats_output_1
     - dataset
     - Dataset containing per-curve statistics (e.g. sign-change time, pre/post window min, max, mean, and other KPIs) computed around the detected sign-change crossing point.

Disciplines
-----------

- data.curve.transform
- data.signal_processing
- data.statistics

Runnable example
----------------

A runnable example is registered for this worker. Open the example workflow on the d3VIEW canvas: `/api/workflow/example?id=curves_sign_change_stats <https://www.d3view.com/api/workflow/example?id=curves_sign_change_stats>`_

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>transformation</code> schema. Worker id: <code>curves_sign_change_stats</code>. Schema hash: <code>5f2c5a702a44</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>