Matrix-Profile Motif Discovery

Install and import#

npm install fintech-algorithms

import { discover } from "fintech-algorithms/geometric-chart-patterns/pattern-matching/matrix-profile-motif-discovery";

Signature#

discover(series, window, exclusionZone)

Computes the matrix profile of a series for a given subsequence length - for each window, the distance to its nearest non-overlapping neighbour - and reports the closest pair, the motif. Every subsequence is z-normalized first, so repeated shapes are found regardless of level.

Parameters#

Returns#

{ window: number; exclusion_zone: number; profile: Array<number | null>; profile_index: Array<number | null>; motif_pair: number[]; motif_distance: number; normalization: string }

An object echoing window and the resolved exclusion_zone, with profile giving each subsequence's nearest-neighbour distance and profile_index the index of that neighbour, both null where a constant subsequence made the comparison impossible. motif_pair is the closest admissible pair of start indexes in ascending order, motif_distance their distance, and normalization is always population-z-score-per-subsequence.

Errors#

• When series holds fewer than six values, or any value is not a finite number — throws Error
• When window is not an integer, is below 3, or exceeds half the series length — throws Error
• When the exclusion zone override is not a nonnegative integer — throws Error
• When no pair of subsequences survives the constant and exclusion-zone filters — throws Error

Complexity: time O(n^2 * window), space O(n * window).

Worked example#

executed This entry is a thin wrapper its test never calls directly, so it was invoked with the arguments its shared implementation received. Real output, not asserted against a published figure.

Input#

[99.881237, 100.116364, 100.33311, 100.355799, 100.226037, 100.187182]

Showing 6 of 120 elements.

16

null

Call#

discover(series, window, exclusionZone)

Returns#

object with 7 fields: window, exclusion_zone, profile, profile_index, motif_pair, motif_distance, normalization

{
  "window": 16,
  "exclusion_zone": 8,
  "profile": [
    1.442017209318879,
    1.4259996875986038,
    1.5353435003673506,
    1.6155150461182326,
    1.885889075174815,
    3.93842156909414
  ],
  "profile_index": [12, 13, 14, 15, 15, 53],
  "motif_pair": [20, 72],
  "motif_distance": 3.6400104112014625e-15,
  "normalization": "population-z-score-per-subsequence"
}

Diagrams#

Calculation flow#

flowchart LR
    A["Validate sequence roles and clocks"] --> B["Apply declared local normalization"]
    B --> C["Enumerate eligible search space"]
    C --> D["Calculate distance, path, profile, or gain"]
    D --> E{"Candidate eligible?"}
    E -->|No| R["INELIGIBLE with reason"]
    E -->|Yes| F["Apply exclusion, radius, threshold, and tie rules"]
    F --> G["Return result plus complete diagnostics"]
    G --> H["Evaluate separately from financial usefulness"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• Foundations of Technical Analysis — Andrew W. Lo, Harry Mamaysky, and Jiang Wang
• SciPy `find_peaks` — SciPy project
• The Probability of Backtest Overfitting — David H. Bailey, Jonathan M. Borwein, Marcos López de Prado, and Qiji Jim Zhu
• Matrix Profile I: All Pairs Similarity Joins for Time Series — Chin-Chia Michael Yeh, Yan Zhu, Liudmila Ulanova, Nurjahan Begum, Yifei Ding, Hoang Anh Dau, Diego Furtado Silva, Abdullah Mueen, and Eamonn Keogh
• Applicability decision

The rest of the Pattern Matching family#

• Normalized Template MatchingSlides a template over a series and finds the window whose shape is closest to it.
• Dynamic-Time-Warping Pattern MatchMeasures how far a query is from a candidate under dynamic time warping, which lets the two series stretch against each other i…
• Shapelet Pattern ClassifierLabels a series by how closely its best-matching window resembles a shapelet.