Time Series Reasoning Agent

A powerful agent-based system for analyzing time series data with specialized tools.

Overview

This Time Series Reasoning Agent uses LangGraph to orchestrate a workflow that performs detailed analysis of time series data. It integrates multiple specialized tools for noise analysis, pattern detection, seasonality decomposition, and anomaly detection.

Features

• Multi-step Analysis Pipeline: Initial assessment, planning, tool selection, and final answer generation
• Rich Visualization: Automatic generation of time series visualizations for better analysis
• Comprehensive Toolset:
  • Noise analysis and classification
  • Trend and seasonality decomposition (STL)
  • Anomaly detection
  • Pattern classification
  • Correlation analysis between multiple time series
  • Fluctuation analysis

Tools

The agent has access to the following tools:

1. datapoint_value: Get the exact value at a specific point in a time series
2. datarange_value: Get a range of values from a time series
3. stl_decomposition: Decompose a time series into trend, seasonal, and residual components
4. anomaly_detection: Detect anomalies in a time series using autoregression
5. anomaly_detection_multi: Detect anomalies in all time series at once
6. classification: Classify patterns in a time series window
7. classification_multi: Classify patterns in all time series at a given position
8. trend_correlation: Analyze trend correlation between time series
9. fluctuation_correlation: Analyze fluctuation correlation based on matching anomalies
10. analyze_noise: Analyze noise characteristics in time series data
11. detect_noise_level: Classify noise level in time series data

Architecture

The agent uses a LangGraph workflow with the following nodes:

1. Initial Analysis: Provides a first assessment of the time series data
2. Planning and Tool Selection: Decides which tools to use next based on the analysis
3. Generate Answer: Creates a final answer based on all gathered information

Usage

from ts_reasoning_agent import answer_question_langgraph
from langchain_openai import ChatOpenAI

# Example time series data
timeseries = [
    [0.01 * i for i in range(256)],  # First time series
    [0.02 * i for i in range(256)]   # Second time series
]
cols = ["ts1", "ts2"]  # Names of the time series

# Question to answer
question = "What are the main anomalies in the time series data?"

# Answer the question using the agent
answer, tool_calls, conversation = answer_question_langgraph(
    question=question,
    timeseries=timeseries,
    cols=cols,
    model="gpt-4",
    client=openai_client,
    max_tool_calls=5
)

print(f"Answer: {answer}")
print(f"Tool calls used: {tool_calls}")

Example

To run the example:

python example.py

This will analyze a test case from a dataset and output the analysis results.

Requirements

• Python 3.8+
• LangChain
• LangGraph
• NumPy
• SciPy
• Pandas
• Matplotlib
• PyWavelets
• Statsmodels
• ADTK (Anomaly Detection Toolkit)