Skip to content

Volatility Indicators

Volatility indicators measure the magnitude of price fluctuations.

ATR - Average True Range

The Average True Range is a volatility indicator. In numta, it is implemented in the momentum indicators module alongside other indicators that use true range calculations.

ATR 

ATR(high: Union[ndarray, list], low: Union[ndarray, list], close: Union[ndarray, list], timeperiod: int = 14) -> np.ndarray

Average True Range (ATR)

The Average True Range (ATR) is a volatility indicator that measures the average range of price movement. It was developed by J. Welles Wilder and is widely used to assess market volatility.

ATR is particularly useful for: - Setting stop-loss levels - Position sizing based on volatility - Identifying breakout potential - Comparing volatility across different instruments

Parameters

high : array-like High prices array low : array-like Low prices array close : array-like Close prices array timeperiod : int, optional Number of periods for the indicator (default: 14)

Returns

np.ndarray Array of ATR values with NaN for the lookback period

Notes

  • Compatible with TA-Lib ATR signature
  • Uses Numba JIT compilation for maximum performance
  • The first timeperiod values will be NaN
  • ATR is always positive (measures absolute volatility, not direction)
  • Higher ATR indicates higher volatility
  • Lower ATR indicates lower volatility

Formula

  1. Calculate True Range (TR) for each bar: TR = max(high - low, |high - prev_close|, |low - prev_close|)

  2. Calculate ATR using Wilder's smoothing: First ATR = average of first timeperiod TR values Subsequent ATR = ((prev_ATR × (timeperiod - 1)) + current_TR) / timeperiod

Lookback period: timeperiod (For timeperiod=14, lookback=14)

Interpretation: - ATR measures volatility, not direction - Rising ATR indicates increasing volatility - Falling ATR indicates decreasing volatility - ATR is often used with multiples (e.g., 2×ATR for stop-loss) - Compare current ATR to historical ATR for context - Higher timeframes generally have higher ATR values

Common Uses: - Stop-loss placement: Close - (2 × ATR) for long positions - Position sizing: Risk a fixed dollar amount per ATR unit - Breakout confirmation: Look for ATR expansion on breakouts - Trend strength: Higher ATR often accompanies strong trends

Examples

import numpy as np from numta import ATR high = np.array([48, 49, 50, 51, 52, 51, 50, 49, 50, 51, 52]) low = np.array([46, 47, 48, 49, 50, 49, 48, 47, 48, 49, 50]) close = np.array([47, 48, 49, 50, 51, 50, 49, 48, 49, 50, 51]) atr = ATR(high, low, close, timeperiod=5) print(atr)

Source code in src/numta/api/momentum_indicators.py 
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
def ATR(high: Union[np.ndarray, list],
        low: Union[np.ndarray, list],
        close: Union[np.ndarray, list],
        timeperiod: int = 14) -> np.ndarray:
    """
    Average True Range (ATR)

    The Average True Range (ATR) is a volatility indicator that measures
    the average range of price movement. It was developed by J. Welles Wilder
    and is widely used to assess market volatility.

    ATR is particularly useful for:
    - Setting stop-loss levels
    - Position sizing based on volatility
    - Identifying breakout potential
    - Comparing volatility across different instruments

    Parameters
    ----------
    high : array-like
        High prices array
    low : array-like
        Low prices array
    close : array-like
        Close prices array
    timeperiod : int, optional
        Number of periods for the indicator (default: 14)

    Returns
    -------
    np.ndarray
        Array of ATR values with NaN for the lookback period

    Notes
    -----
    - Compatible with TA-Lib ATR signature
    - Uses Numba JIT compilation for maximum performance
    - The first timeperiod values will be NaN
    - ATR is always positive (measures absolute volatility, not direction)
    - Higher ATR indicates higher volatility
    - Lower ATR indicates lower volatility

    Formula
    -------
    1. Calculate True Range (TR) for each bar:
       TR = max(high - low, |high - prev_close|, |low - prev_close|)

    2. Calculate ATR using Wilder's smoothing:
       First ATR = average of first timeperiod TR values
       Subsequent ATR = ((prev_ATR × (timeperiod - 1)) + current_TR) / timeperiod

    Lookback period: timeperiod
    (For timeperiod=14, lookback=14)

    Interpretation:
    - ATR measures volatility, not direction
    - Rising ATR indicates increasing volatility
    - Falling ATR indicates decreasing volatility
    - ATR is often used with multiples (e.g., 2×ATR for stop-loss)
    - Compare current ATR to historical ATR for context
    - Higher timeframes generally have higher ATR values

    Common Uses:
    - Stop-loss placement: Close - (2 × ATR) for long positions
    - Position sizing: Risk a fixed dollar amount per ATR unit
    - Breakout confirmation: Look for ATR expansion on breakouts
    - Trend strength: Higher ATR often accompanies strong trends

    Examples
    --------
    >>> import numpy as np
    >>> from numta import ATR
    >>> high = np.array([48, 49, 50, 51, 52, 51, 50, 49, 50, 51, 52])
    >>> low = np.array([46, 47, 48, 49, 50, 49, 48, 47, 48, 49, 50])
    >>> close = np.array([47, 48, 49, 50, 51, 50, 49, 48, 49, 50, 51])
    >>> atr = ATR(high, low, close, timeperiod=5)
    >>> print(atr)
    """
    # Validate inputs
    if timeperiod < 1:
        raise ValueError("timeperiod must be >= 1")

    # Convert to numpy arrays if needed
    high = np.asarray(high, dtype=np.float64)
    low = np.asarray(low, dtype=np.float64)
    close = np.asarray(close, dtype=np.float64)

    # Validate input lengths
    n = len(high)
    if len(low) != n or len(close) != n:
        raise ValueError("All input arrays must have the same length")

    if n == 0:
        return np.array([], dtype=np.float64)

    # Not enough data points - return all NaN
    if n <= timeperiod:
        return np.full(n, np.nan, dtype=np.float64)

    # Pre-allocate output array and run Numba-optimized calculation
    output = np.empty(n, dtype=np.float64)
    _atr_numba(high, low, close, timeperiod, output)

    return output

NATR - Normalized Average True Range

NATR 

NATR(high: Union[ndarray, list], low: Union[ndarray, list], close: Union[ndarray, list], timeperiod: int = 14) -> np.ndarray

Normalized Average True Range (NATR)

NATR is a normalized version of the Average True Range (ATR) that expresses volatility as a percentage of the closing price. This normalization allows for better comparison of volatility across securities with different price levels.

By expressing ATR as a percentage, NATR provides a standardized measure that can be compared across different instruments, timeframes, and price levels.

Parameters

high : array-like High prices array low : array-like Low prices array close : array-like Close prices array timeperiod : int, optional Period for ATR calculation (default: 14)

Returns

np.ndarray Array of NATR values (percentage)

Notes

  • Compatible with TA-Lib NATR signature
  • Values expressed as percentages (0-100+)
  • Normalizes volatility for cross-security comparison
  • Lookback period same as ATR

Formula

NATR = (ATR / Close) * 100

Where ATR is the Average True Range over the specified period.

Interpretation: - Higher NATR: Higher volatility relative to price - Lower NATR: Lower volatility relative to price - Rising NATR: Increasing volatility - Falling NATR: Decreasing volatility - NATR useful for position sizing - Compare NATR across different securities

Advantages: - Normalized for price level - Comparable across securities - Percentage-based (easier interpretation) - Accounts for gaps (uses True Range) - Smoothed measure (uses ATR)

Advantages over ATR: - Can compare different securities - Not affected by absolute price - Better for multi-security analysis - Useful for percentage-based stops

Common Uses: - Volatility comparison across securities - Position sizing (normalize by volatility) - Stop loss placement (percentage-based) - Volatility filtering (trade selection) - Risk management - Volatility breakout detection

Trading Applications: - High NATR: Reduce position size (higher risk) - Low NATR: Increase position size (lower risk) - Stop loss: Place at NATR% below entry - Filter: Only trade when NATR in range - Breakout: Enter when NATR expands

Position Sizing Example: Risk per trade = Account * 0.02 (2%) Position size = Risk / (NATR * Price / 100)

Comparison with Related Indicators: - ATR: Absolute volatility measure - NATR: Percentage volatility measure - Bollinger Bands: Volatility bands - Standard Deviation: Statistical volatility

Examples

import numpy as np from numta import NATR high = np.array([110, 112, 111, 113, 115, 114, 116, 118]) low = np.array([100, 102, 101, 103, 105, 104, 106, 108]) close = np.array([105, 107, 106, 108, 110, 109, 111, 113]) natr = NATR(high, low, close, timeperiod=14)

Values are percentages representing volatility

See Also

ATR : Average True Range TRANGE : True Range

Source code in src/numta/api/volatility_indicators.py 
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
def NATR(high: Union[np.ndarray, list],
         low: Union[np.ndarray, list],
         close: Union[np.ndarray, list],
         timeperiod: int = 14) -> np.ndarray:
    """
    Normalized Average True Range (NATR)

    NATR is a normalized version of the Average True Range (ATR) that expresses
    volatility as a percentage of the closing price. This normalization allows for
    better comparison of volatility across securities with different price levels.

    By expressing ATR as a percentage, NATR provides a standardized measure that
    can be compared across different instruments, timeframes, and price levels.

    Parameters
    ----------
    high : array-like
        High prices array
    low : array-like
        Low prices array
    close : array-like
        Close prices array
    timeperiod : int, optional
        Period for ATR calculation (default: 14)

    Returns
    -------
    np.ndarray
        Array of NATR values (percentage)

    Notes
    -----
    - Compatible with TA-Lib NATR signature
    - Values expressed as percentages (0-100+)
    - Normalizes volatility for cross-security comparison
    - Lookback period same as ATR

    Formula
    -------
    NATR = (ATR / Close) * 100

    Where ATR is the Average True Range over the specified period.

    Interpretation:
    - Higher NATR: Higher volatility relative to price
    - Lower NATR: Lower volatility relative to price
    - Rising NATR: Increasing volatility
    - Falling NATR: Decreasing volatility
    - NATR useful for position sizing
    - Compare NATR across different securities

    Advantages:
    - Normalized for price level
    - Comparable across securities
    - Percentage-based (easier interpretation)
    - Accounts for gaps (uses True Range)
    - Smoothed measure (uses ATR)

    Advantages over ATR:
    - Can compare different securities
    - Not affected by absolute price
    - Better for multi-security analysis
    - Useful for percentage-based stops

    Common Uses:
    - Volatility comparison across securities
    - Position sizing (normalize by volatility)
    - Stop loss placement (percentage-based)
    - Volatility filtering (trade selection)
    - Risk management
    - Volatility breakout detection

    Trading Applications:
    - High NATR: Reduce position size (higher risk)
    - Low NATR: Increase position size (lower risk)
    - Stop loss: Place at NATR% below entry
    - Filter: Only trade when NATR in range
    - Breakout: Enter when NATR expands

    Position Sizing Example:
    Risk per trade = Account * 0.02 (2%)
    Position size = Risk / (NATR * Price / 100)

    Comparison with Related Indicators:
    - ATR: Absolute volatility measure
    - NATR: Percentage volatility measure
    - Bollinger Bands: Volatility bands
    - Standard Deviation: Statistical volatility

    Examples
    --------
    >>> import numpy as np
    >>> from numta import NATR
    >>> high = np.array([110, 112, 111, 113, 115, 114, 116, 118])
    >>> low = np.array([100, 102, 101, 103, 105, 104, 106, 108])
    >>> close = np.array([105, 107, 106, 108, 110, 109, 111, 113])
    >>> natr = NATR(high, low, close, timeperiod=14)
    >>> # Values are percentages representing volatility

    See Also
    --------
    ATR : Average True Range
    TRANGE : True Range
    """
    # Validate inputs
    if timeperiod < 1:
        raise ValueError("timeperiod must be >= 1")

    # Convert to numpy arrays
    high = np.asarray(high, dtype=np.float64)
    low = np.asarray(low, dtype=np.float64)
    close = np.asarray(close, dtype=np.float64)

    n = len(high)
    if len(low) != n or len(close) != n:
        raise ValueError("high, low, and close must have the same length")

    if n == 0:
        return np.array([], dtype=np.float64)

    # Calculate using Numba implementation
    output = np.empty(n, dtype=np.float64)
    _natr_numba(high, low, close, timeperiod, output)

    return output

TRANGE - True Range

TRANGE 

TRANGE(high: Union[ndarray, list], low: Union[ndarray, list], close: Union[ndarray, list]) -> np.ndarray

True Range (TRANGE)

True Range measures volatility by taking the maximum of: - Current high - current low - Absolute value of current high - previous close - Absolute value of current low - previous close

Parameters

high : array-like High prices array low : array-like Low prices array close : array-like Close prices array

Returns

np.ndarray Array of true range values

See Also

ATR : Average True Range NATR : Normalized Average True Range

Source code in src/numta/api/volatility_indicators.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def TRANGE(high: Union[np.ndarray, list],
           low: Union[np.ndarray, list],
           close: Union[np.ndarray, list]) -> np.ndarray:
    """
    True Range (TRANGE)

    True Range measures volatility by taking the maximum of:
    - Current high - current low
    - Absolute value of current high - previous close
    - Absolute value of current low - previous close

    Parameters
    ----------
    high : array-like
        High prices array
    low : array-like
        Low prices array
    close : array-like
        Close prices array

    Returns
    -------
    np.ndarray
        Array of true range values

    See Also
    --------
    ATR : Average True Range
    NATR : Normalized Average True Range
    """
    high = np.asarray(high, dtype=np.float64)
    low = np.asarray(low, dtype=np.float64)
    close = np.asarray(close, dtype=np.float64)

    n = len(high)
    if len(low) != n or len(close) != n:
        raise ValueError("high, low, and close must have the same length")

    if n == 0:
        return np.array([], dtype=np.float64)

    output = np.empty(n, dtype=np.float64)
    _trange_numba(high, low, close, output)

    return output