Time Series Search (TSS)

This page describes the Time Series Search (TSS) parameters as part of AI libs.

Time Series Search (TSS) is a method for finding similarities or patterns within sequential data that changes over time. Unlike static vector search, TSS focuses on comparing temporal sequences, often accounting for shifts, distortions, or varying lengths in the data. Techniques like dynamic time warping (DTW) or similarity joins are used to align sequences and measure their closeness. TSS is widely applied in domains such as finance, IoT, and healthcare, where identifying repeating trends, anomalies, or correlations in time-dependent data is critical.

.ai.tss.tss

The .ai.tss.tss function function conducts a Time Series Subsequence (TSS) search with z-normalization, returning the k nearest neighbors.

Z-normalization ensures that subsequences are compared on a standardized scale, removing the effects of shifts in mean and variance. This allows for more accurate detection of similar temporal patterns across varying time series.

Parameters

Name	Type(s)	Description
ts	short[] | int[] | long[] | float[] | real[]	The data vector
q	short[] | int[] | long[] | float[] | real[]	The query vector
k	short | long | int	The number of nearest neighbors to return
opts	dict	Advanced options (optional): - ignoreErrors (default false): if true, allowsK k > count[ts] (k set to count[ts]) and q longer than ts (returns empty). - returnMatches (default false): if true, returns a list of distances, indexes, and matched patterns. - normalize (default true): if true, applies z-normalization to query and timeseries windows. - overlap (default 0.0): minimum distance between results expressed in ratio of of query size.

Returns

Type	Description
(float[]; long[])	List of distances and indexes

Example

q).ai:use`kx.ai
q).ai.tss.tss[10?1f;3?1f;5;::]

0.9182925 0.9312366 1.44556 2.310831 2.842262
2         6         1       4        7

The example compares a 10-point time series with a 3-point query sequence, requesting the 5 nearest subsequence matches. The output shows the z-normalized distances (top row) and the starting indices of the best matches (bottom row). This demonstrates how .ai.tss.tss identifies subsequences that are most similar to the query after normalization.

.ai.tss.tssdist

The .ai.tss.tssdist function creates a list of sliding z-normalized distances between a query and subsequences within a time series.

By normalizing at each step, it produces consistent distance values that highlight true structural similarities rather than raw value differences. The output is useful for identifying candidate matches and analyzing local alignments.

Parameters

Name	Type(s)	Description
ts	sshort[] | int[] | long[] | float[] | real[]	The data vector
q	sshort[] | int[] | long[] | float[] | real[]	The query vector
opts	dict	Advanced options (optional): - normalize (default true): if true, applies z-normalization to query and timeseries windows

Returns

Type	Description
float[]	The TSS distances among all possible positions

Example

q).ai:use`kx.ai
q).ai.tss.tssdist[10?1f;3?1f;::]

0.1624568 0.6407308 0.9527249 0.8994361 0.6351341 0.8521289 0.9975543 0.8938303

Here, the function computes the z-normalized distance between the query sequence and every possible subsequence of the 10-point time series. The output is a sliding list of distances, one for each alignment position. This illustrates how .ai.tss.tssdist can be used to analyze similarity patterns across the entire series, not just the top matches.