DOCSEARCHbyAlgolia
Submit Docs

talipp Documentation

repository·main·Indexed 19 days ago

https://github.com/nardew/talipp

talipp is an incremental technical analysis library for Python optimized for real-time financial applications. It provides a wide range of financial indicators supporting O(1) time complexity for delta input operations, including appending, updating, and removing data points. The library supports chaining indicators into pipelines, handling both float and OHLCV input types, and implements the collections.abc.Sequence interface for easy data access.

Tokens
7.3K
Snippets
30
Records
33
Agent score
59%

What's inside talipp

  1. How timeframe auto-sampling works

    main

    Timeframe auto-sampling is a feature for indicators using OHLCV input. Instead of adding a new output value for every single input received, the indicator 'merges' multiple inputs that fall within the same selected timeframe. It keeps only the last value received within that period.

    This is particularly useful for real-time applications that receive high-frequency data (e.g., hundreds of updates per second) but require indicators to be calculated on a specific sampled timeframe like 1 minute or 15 seconds.

    # Example of the merging behavior
obv = OBV(input_sampling=SamplingPeriodType.SEC_15)

# 00:00:00 -> New timeframe starts, length becomes 1
obv.add(OHLCV(..., time=dt.replace(second=0)))

# 00:00:13 -> Still within the same 15s window, length stays 1 (last value updated)
obv.add(OHLCV(..., time=dt.replace(second=13)))

# 00:00:17 -> New 15s window started, length becomes 2
obv.add(OHLCV(..., time=dt.replace(second=17)))

  2. Understand indicator input types (float vs OHLCV)

    main

    Indicators in talipp support two types of input data depending on their requirements:

    1. float: Used for indicators that only require a plain series of numbers (e.g., SMA).
    2. OHLCV: Used for indicators that require price action data (Open, High, Low, Close) and optionally Volume and Time (e.g., Stoch).

    You can determine which type an indicator requires by checking the type of the input_values parameter in its __init__ method or by consulting its documentation.

    from talipp.indicators import SMA, Stoch
from talipp.ohlcv import OHLCV

# SMA consumes floats
sma = SMA(period=3, input_values=[1, 2, 3])

# Stoch consumes OHLCV objects
stoch = Stoch(period=3, smoothing_period=2, input_values=[OHLCV(1, 2, 3, 4), OHLCV(5, 6, 7, 8)])

  3. How incremental operations work in talipp

    main

    talipp is designed for real-time applications using an incremental architecture. Instead of recalculating an entire vector of data ($O(n)$), it calculates new indicator values based only on the delta input data ($O(1)$).

    Supported incremental operations include:

    • Appending: Adding new values to the end of the input.
    • Updating: Modifying the most recently added input value.
    • Removing: Deleting an arbitrary number of the most recent input values.

    This makes talipp highly efficient for applications with frequent Create, Update, and Delete (CUD) operations on time-series data.

  4. Use float or OHLCV as indicator inputs

    main

    Indicators specify the type of data they require. talipp supports two primary input types:

    1. Simple types: Such as float (e.g., for SMA).
    2. Complex types: Such as OHLCV from talipp.ohlcv, which encapsulates Open, High, Low, Close, and Volume data (e.g., for Stoch).

    Ensure the input type matches the requirements of the specific indicator you are using.

    from talipp.indicators import SMA, Stoch
from talipp.ohlcv import OHLCV

# SMA accepts float
sma = SMA(period=3, input_values=[1, 2, 3])

# Stoch accepts OHLCV objects
stoch = Stoch(period=3, smoothing_period=2, input_values=[
    OHLCV(1, 2, 3, 4), 
    OHLCV(5, 6, 7, 8)
])

  5. Chain multiple indicators into a pipeline

    main

    You can create a computation pipeline by linking indicators together. When indicators are chained, the output of one indicator automatically becomes the input for the next. This allows you to build complex, custom indicators or smoothed versions of existing ones.

    To chain indicators, pass the preceding indicator instance to the input_indicator parameter during initialization. Once chained, adding a value to the first indicator in the chain will automatically propagate values through the entire pipeline.

    from talipp.indicators import SMA

sma1 = SMA(2)
sma2 = SMA(2, input_indicator=sma1)

sma1.add(1)
sma1.add(2)
sma1.add(3)
# sma2 will automatically receive values from sma1 as they become available

  6. Understand indicator output types

    main

    In talipp, indicator outputs can be either simple float values or complex objects.

    • Simple outputs: Indicators like SMA return a single float for each input value.
    • Complex outputs: Indicators that require multiple values per data point (e.g., Bollinger Bands returning lower, central, and upper bands) return a complex type defined as a Python dataclass.

    Each indicator module documents its specific complex output type. For example, the Bollinger Bands indicator returns BBVal objects.

  7. Apply auto-sampling to float-based indicators

    main

    Indicators that accept float inputs (like MACD) do not support input_sampling directly. To use auto-sampling with these indicators, you must wrap your float values in OHLCV objects and use an input_modifier to extract the value back out.

    Steps:

    1. Wrap each float in an OHLCV object, setting the close field to your value and providing a time.
    2. Pass the list of OHLCV objects to input_values.
    3. Provide a lambda or function to input_modifier that extracts the desired field (e.g., lambda x: x.close).
    4. Set input_sampling as usual.
    from datetime import datetime
from talipp.indicators import MACD
from talipp.input import SamplingPeriodType
from talipp.ohlcv import OHLCV

input_floats = [1.0, 2.0, 3.0]
dt = datetime(2024, 1, 1, 0, 0, 0)

# 1. Wrap floats in OHLCV
input_ohlcv = [OHLCV(None, None, None, value, None, dt) for value in input_floats]

# 2, 3, 4. Initialize with modifier and sampling
macd = MACD(
    input_values=input_ohlcv, 
    input_modifier=lambda x: x.close, 
    input_sampling=SamplingPeriodType.SEC_15
)

  8. Perform incremental operations on indicators

    main

    talipp indicators support three primary incremental operations that allow you to manage data streams without recalculating the entire history:

    1. Adding: Use .add(value) to append a new input value to the series.
    2. Updating: Use .update(value) to change the most recently added input value.
    3. Removing: Use .remove() to delete the most recently added input value.

    This approach ensures that updates are reflected in the indicator's values in O(1) time complexity.

    from talipp.indicators import SMA

# Initialize with a period and initial values
sma = SMA(period=3, input_values=[1, 2, 3, 4])

# Append a new value
sma.add(5)

# Update the last value
sma.update(8)

# Remove the last value
sma.remove()

  9. Install talipp

    main
    talipp (also known as tali++) is a Python library for financial technical analysis indicators. It is designed for real-time applications using incremental computation, allowing for O(1) updates when adding, updating, or removing input values, rather than recalculating the entire series.

  11. Install talipp via pip

    main

    You can install the stable version of talipp from PyPI using pip. If you need the latest development version from the GitHub repository, you can install it directly from the main branch.

    # Install stable version
pip install talipp

# Install latest from GitHub
pip install git+https://github.com/nardew/talipp.git@main
    pip install talipp

  12. Perform incremental updates on indicators

    main

    Indicators in talipp behave like lists and provide methods to modify the underlying data stream incrementally without re-initializing the entire indicator.

    • add(value): Appends a new value.
    • update(value): Changes the last added value.
    • remove(): Removes the last added value.
    • purge_oldest(n): Removes the $n$ oldest input values.
    from talipp.indicators import EMA

# Initialize with starting values
ema = EMA(period=3, input_values=[1, 3, 5, 7, 9])

# Append a new value
ema.add(11)

# Update the last value (e.g., if the last price was corrected)
ema.update(15)

# Remove the last value
ema.remove()

# Purge the oldest N values to manage memory or window size
ema.purge_oldest(1)
    from talipp.indicators import EMA

ema = EMA(period=3, input_values=[1, 3, 5, 7, 9])
ema.add(11)
ema.update(15)
ema.remove()
ema.purge_oldest(1)