Installation & Usage

Install this tool and use it with the AI SDK

1. Install the package

npm install @tpmjs/tools-time-series-decompose-lite

pnpm add @tpmjs/tools-time-series-decompose-lite

yarn add @tpmjs/tools-time-series-decompose-lite

bun add @tpmjs/tools-time-series-decompose-lite

deno add npm:@tpmjs/tools-time-series-decompose-lite

2. Import the tool

import { timeSeriesDecomposeLiteTool } from '@tpmjs/tools-time-series-decompose-lite';

3. Use with AI SDK

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { timeSeriesDecomposeLiteTool } from '@tpmjs/tools-time-series-decompose-lite';

const result = await generateText({
  model: openai('gpt-4o'),
  tools: { timeSeriesDecomposeLiteTool },
  prompt: 'Your prompt here...',
});

console.log(result.text);

Parameters

Available configuration options

Auto-extracted

data

Required

Type: array

Time series data points in chronological order

period

Required

Type: number

Seasonal period (e.g., 12 for monthly data with yearly seasonality, 7 for daily data with weekly patterns)

Schema extracted: 1/1/2026, 8:17:49 AM

README

Time Series Decompose Lite

Simple time series decomposition into trend, seasonal, and residual components using additive decomposition.

Installation

npm install @tpmjs/tools-time-series-decompose-lite

Usage

import { timeSeriesDecomposeLiteTool } from '@tpmjs/tools-time-series-decompose-lite';

// Example: Monthly sales data with yearly seasonality
const result = await timeSeriesDecomposeLiteTool.execute({
  data: [112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118, 115, 126, 141, 135, 125, 149],
  period: 12, // 12 months = 1 year
});

console.log(result);
// {
//   trend: [...],        // Long-term trend
//   seasonal: [...],     // Repeating seasonal pattern
//   residual: [...],     // Random noise
//   period: 12,
//   decompositionType: 'additive',
//   statistics: {
//     trendStrength: 0.85,
//     seasonalStrength: 0.72
//   }
// }

API

Input

data (required): Time series values number[] in chronological order
period (required): Seasonal period as integer (e.g., 12 for monthly data with yearly patterns, 7 for daily data with weekly patterns)

Output

trend: Long-term trend component
seasonal: Repeating seasonal pattern (centered at 0)
residual: Irregular/random component
period: The seasonal period used
decompositionType: Always 'additive'
statistics: Strength of trend and seasonal components (0-1)

Algorithm

Uses classical additive decomposition:

Model: Y(t) = Trend(t) + Seasonal(t) + Residual(t)

Trend Extraction: Centered moving average with window = period
Detrending: Subtract trend from original data
Seasonal Extraction: Average each position in the cycle, then center
Residual: What remains after removing trend and seasonal

Use Cases

Analyze sales patterns (monthly/quarterly/yearly cycles)
Study weather data (daily/seasonal patterns)
Economic indicators (business cycles)
Web traffic analysis (weekly/daily patterns)

Limitations

Requires at least 2 complete periods of data
Assumes additive model (for multiplicative, log-transform data first)
Simple moving average (not robust to outliers)

License

MIT

timeSeriesDecomposeLiteTool

Interactive Playground