findMotif

Find the locations of top motif pairs from the matrix profile of a time series

Since R2025a

Syntax

locs = findMotif(MP,MPI)

locs = findMotif(___,Name=Value)

findMotif(___)

Description

Return Local Motif Locations

locs = findMotif(MP,MPI) returns the starting locations locs of the top motif pairs of a time series from its matrix profile MP and matrix profile indices in MPI as computed by the matrixProfile command.

A motif pair is defined as a pair of subsequences that are most similar to each other among all possible pairs of subsequences in the time series, based on the z-normalized Euclidean distances between all the pair members. matrixProfile determines these distances and findMotif parses the results.

locs = findMotif(___,Name=Value) specifies additional parameters using one or more name-value arguments in addition to the input arguments in previous syntaxes. For example, to limit the number of motif pairs that findMotif returns to 5, set MaxNumMotifs to 5.

Plot Top Motifs

findMotif(___) plots the location of the top motifs on the matrix profile curve.

Input Arguments

MP — Matrix profile

numeric vector

Matrix profile containing the z-normalized Euclidean distances between each subsequence of a specified length and all other subsequences in the time series, specified as a numeric vector. MP is an output of the matrixProfile command.

MPI — Matrix profile index

integer vector

Matrix profile index containing the indices of the starting locations of the subsequences that correspond to each distance value in MP in descending order of importance, specified as an integer vector. MPI is an output of the matrixProfile command.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: loc = findMotif(MP,MPI,MaxNumMotifs=5) limits the number of motifs that findMotif returns to 5.

MinSeparation — Minimum separation between motifs

0 (default) | nonnegative scalar

Minimum separation between motifs, specified as a nonnegative scalar. When MinSeparation is greater than its default value of 0, findMotif selects only the best local motifs in the matrix profile and ignores all other motifs within the specified separation distance.

MaxNumMotifs — Maximum number of motifs

positive integer scalar

Maximum number of motifs to find, specified as a positive integer scalar. findMotif returns the motifs in descending order of importance, from the smallest to the largest values of the matrix profile. If MaxNumMotifs is not specified, findMotif returns all motifs.

Output Arguments

locs — Starting locations of top motif pairs

integer matrix

Starting locations of motif pairs in MP, specified as an n-by-2 or 2-by-n matrix, depending on whether MPI is a column vector or row vector. The elements of locs are sorted in order of descending importance, as indicated by increasing motif-pair distances.

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The findMotif function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2025a