QuanTAlib/lib/core/tseries/TSeries.md

TSeries: Time Series Data

Overview

TSeries is a high-performance container for time-series data. Unlike a standard List<TValue>, it uses a Structure of Arrays (SoA) layout internally. This means it stores timestamps and values in separate contiguous arrays (List<long> and List<double>).

This layout is critical for performance because it allows:

1. SIMD Optimization: The Values property returns a ReadOnlySpan<double> that can be directly processed by CPU vector instructions (AVX/SSE).
2. Cache Locality: Iterating over values doesn't load timestamps into the CPU cache, and vice versa.

Structure

public class TSeries : IReadOnlyList<TValue>
{
    // Internal SoA storage
    protected readonly List<long> _t;
    protected readonly List<double> _v;

    // Public accessors
    public ReadOnlySpan<double> Values => ...; // Zero-copy access
    public ReadOnlySpan<long> Times => ...;    // Zero-copy access
    
    public TValue Last { get; }
    public int Count { get; }
}

Key Features

• SoA Layout: Optimized for numerical computing and SIMD.
• Zero-Copy Access: Values and Times properties expose internal storage as Spans without copying.
• Streaming Support: The Add method supports isNew parameter to handle intra-bar updates (replacing the last value instead of appending).
• Event Publishing: Optional Pub event for reactive pipelines.

Usage

Creating and Adding Data

var series = new TSeries();
series.Add(DateTime.Now, 100.0); // isNew=true by default

Streaming Updates

// New bar
series.Add(time, 100.0, isNew: true);

// Update current bar (e.g. price change within same minute)
series.Add(time, 101.0, isNew: false); 

SIMD Processing

// Calculate average using SIMD
double avg = series.Values.AverageSIMD();