TStrends Documentation

TStrends is a Python package for automated trend labelling in time series data. The philosophy behind it is to make available in Python the state of the art in automatic trend labelling (check the Bibliography for more details). It provides various approaches for identifying trends, estimating returns, and optimizing parameters.

Features

• Labelling: Multiple trend labelling approaches:

  • Binary and ternary trend labelling

  • Continuous trend labelling (CTL)

  • Oracle-based labelling

• Evaluating the labelling: Returns estimation with transaction costs

• Optimizing the labelling: Parameter optimization using Bayesian optimization

• Label Tuning: Transform discrete labels into continuous values expressing trend potential

• Visualization utilities: For visual inspection of trend labels and gradient visualization of tuned labels

Links

• GitHub: https://github.com/agpenas/tstrends

• PyPI: https://pypi.org/project/tstrends

Requirements

• Python 3.11+

• NumPy

• Pandas

• SciPy

• bayesian-optimization

• matplotlib

• Pillow

• Fonttools

Quick Start

Here’s a simple example of how to use TStrends:

from tstrends.trend_labelling import BinaryCTL
from tstrends.returns_estimation import ReturnsEstimatorWithFees
from tstrends.optimization import Optimizer

# Labellers expect a Python list of numeric prices—ints or floats (not a NumPy array)
prices = [100.0, 101.5, 103.0, 101.0, 99.0, 100.5, 102.0]

# Create a trend labeller
labeller = BinaryCTL(omega=0.1)

# Create a returns estimator
estimator = ReturnsEstimatorWithFees()

# Create an optimizer (requires a returns estimator instance)
optimizer = Optimizer(returns_estimator=estimator)

# Use the components together
labels = labeller.get_labels(prices)
returns = estimator.estimate_return(prices, labels)
optimal_params = optimizer.optimize(BinaryCTL, prices)

For more detailed examples, see the Usage Examples page.

Contents

User Guide

• Installation
  • Requirements
  • Installing TStrends
  • Development Installation
• Usage Examples
  • Trend Labelling Examples
  • Returns Estimation Examples
  • Parameter Optimization Example
  • Label Tuning Examples
  • Real-World Application
• Notebook Examples
  • Trend Labelling Catalogue
  • How to Use Simple Labellers
  • Parameter Optimization Example
  • Label Tuning Example

API Reference

• API Reference
  • Modules

Development

• Contributing
  • Getting Started
  • Basic Guidelines
  • Making Changes
  • Need Help?
• Bibliography
  • Academic References

Bibliography

The algorithms implemented in this package are based on or inspired by the following academic papers:

[1] Wu, D., Wang, X., Su, J., Tang, B., & Wu, S. (2020). “A Labeling Method for Financial Time Series Prediction Based on Trends”. Entropy, 22(10), 1162.

The foundation for our Binary CTL (Continuous Trend Labelling) implementation.

[2] Dezhkam, A., Manzuri, M. T., Aghapour, A., Karimi, A., Rabiee, A., & Shalmani, S. M. (2023). “A Bayesian-based classification framework for financial time series trend prediction”. The Journal of supercomputing, 79(4), 4622–4659.

Inspired our Ternary CTL implementation.

[3] Kovačević, T., Merćep, A., Begušić, S., & Kostanjčar, Z. (2023). “Optimal Trend Labeling in Financial Time Series”. IEEE Access. PP. 1-1.

The basis for our Oracle Binary and Ternary Trend Labellers.

For a more comprehensive bibliography with detailed descriptions, see the Bibliography page.