TimeSeries Management
Functions for creating, transforming, and merging time series data. Master the core data structures that power kScript indicators and build complex data processing workflows.
Overview
Data Transformation
Transform existing time series data using custom functions to create new indicators, perform calculations, and generate derived datasets for advanced analysis.
Data Extraction & Alignment
Extract specific columns from time series data and align timestamps between different data sources for synchronized multi-indicator analysis.
Functions Reference
buildTimeseries - create new TimeSeries by applying transformation function
buildTimeseries(srcTimeSeries: TimeSeries, transformFunc: (bar: number[], idx: number) => number[]): TimeSeriesParameters:
- srcTimeSeries (TimeSeries) - Source TimeSeries
- transformFunc (function) - Transformation function to apply to each bar
Returns:
TimeSeries (new transformed TimeSeries)
Code Example:
matchTimestamp - align timestamps between different data sources
matchTimestamp(sourceTimeSeries: TimeSeries, targetTimeSeries: TimeSeries, matchMode?: string): TimeSeriesParameters:
- sourceTimeSeries (TimeSeries) - Source TimeSeries with timestamps to match
- targetTimeSeries (TimeSeries) - Target TimeSeries to match against
- matchMode (string) - Matching mode: "exact", "closest", or "contains" (default: "contains")
Returns:
TimeSeries (aligned TimeSeries with matched timestamps)
Code Example:
timeseries - extract specific column from TimeSeries data
timeseries(arr: TimeSeries, priceIndex: number): TimeSeriesParameters:
- arr (TimeSeries) - Source TimeSeries data
- priceIndex (number) - Index of the column to extract (0-based)
Returns:
TimeSeries (single-column TimeSeries)
Code Example:
Common Usage Patterns
Custom Indicator Creation
Build a custom momentum indicator using buildTimeseries
Multi-Source Data Alignment
Align different data sources using matchTimestamp for synchronized analysis
Column Extraction & Processing
Extract specific columns and create derived indicators
Best Practices
Transformation Functions
Keep transformation functions simple and fast. Complex calculations in buildTimeseries can impact performance on large datasets.
Data Validation
Always check if data exists at the current index before accessing it. Use conditional logic to handle missing data gracefully.
Timestamp Matching
Use 'exact' mode for perfect timestamp alignment, 'closest' for finding nearest timestamps, and 'contains' for time range inclusion. Choose based on your data source characteristics.
Column Extraction
When using timeseries() to extract columns, remember that the resulting series has priceIndex 1 for most functions since it becomes single-column data.
Data Source Alignment
Always align secondary data sources to your primary chart timeframe using matchTimestamp before performing cross-source analysis to ensure temporal consistency.