Directional Trend Index
Install and import#
npm install fintech-algorithmsimport { directionalTrendIndex } from "fintech-algorithms/technical-indicators/trend-systems/directional-trend-index";Signature#
directionalTrendIndex(input)Wilder-smooths the net of the upward high moves against the downward low moves, and divides it by the smoothed total of both, giving a signed percentage that runs from -100 to 100.
Parameters#
| Name | Type | Notes |
|---|---|---|
input | TopicInput | bars is the OHLCV series, validated for finite prices, strictly increasing timestamp, a single adjustment basis, non-negative volume, and a high and low that bracket the other prices. From parameters this topic reads only period (integer, minimum 2, default 14), the Wilder smoothing length applied to both the difference and the total. |
Returns#
TopicResult
series and latest carry a single value key. A bar is null when the smoothed total of the moves is zero. The warm-up runs one bar past the period because the first bar has no prior high or low to move from.
Warm-up#
The first period bars (14 by default) positions are null. The move series is undefined on the first bar, so the Wilder seed closes at index period: with the default period indices 0 to 13 are null and ready_at is 14.
Errors#
- When
parameters.periodis present but is not an integer of at least 2 — throws Error - When
barsis empty, or a bar has a non-finite price, a negative volume, a timestamp not greater than the previous one, or a high below its open, low, or close — throws Error
Complexity: time O(n),
space O(n).
Worked example#
executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.
Input#
{
"bars": [
{
"timestamp": "2024-01-02",
"basis": "synthetic-unadjusted",
"open": 100,
"high": 101.45,
"low": 98.695,
"close": 100,
"volume": 750000,
"benchmark": 200
},
{
"timestamp": "2024-01-03",
"basis": "synthetic-unadjusted",
"open": 101.49111452,
"high": 103.38381693,
"low": 100.05480022,
"close": 101.78791214,
"volume": 795117,
"benchmark": 200.56326135
},
{
"timestamp": "2024-01-04",
"basis": "synthetic-unadjusted",
"open": 102.45519048,
"high": 104.6701838,
"low": 100.91147007,
"close": 102.9549389,
"volume": 840234,
"benchmark": 201.11020913
}
],
"parameters": {}
}Call#
directionalTrendIndex(input)Returns#
object with 9 fields: topic_id, title, state, ready, ready_at, series, latest, parameters, …
{
"topic_id": "D07-F02-A18",
"title": "Directional Trend Index",
"state": "calculated",
"ready": true,
"ready_at": 14,
"series": {
"value": [null, null, null, null, null, null]
},
"latest": {
"value": -37.841395713258386
},
"parameters": {},
"diagnostics": {
"causal": true,
"input_count": 96
}
}Diagrams#
Calculation flow#
Directional Trend Index calculation flow
flowchart LR
A["ordered OHLC or close observations with explicit window, s"] --> B["Validate order, basis, and finite values"]
B --> C["Apply the selected Directional Trend Index convention"]
C --> D["Emit value, readiness, and diagnostics"]
D --> E["Interpret descriptively; test outcomes separately"]
B -->|invalid or insufficient| X["Withhold output with a reason"]
Directional Trend Index readiness and evidence states
stateDiagram-v2
[*] --> Waiting
Waiting --> Ready: enough valid causal observations
Waiting --> Rejected: malformed or unsupported input
Ready --> Calculated: selected formula applied
Calculated --> Interpreted: diagnostic and limitation retained
Interpreted --> Ready: next observation arrives
Rejected --> Waiting: corrected input and deterministic reset
How it works#
This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.
References#
- TA-Lib function groups — see linked primary or authoritative record
- TA-Lib C/C++ API — see linked primary or authoritative record
- TA-Lib maintained source — see linked primary or authoritative record
- Evidence decision
- Level 1 evidence map