Package {matrixprofiler}

Type:	Package
Title:	Matrix Profile for R
Version:	0.1.12
Maintainer:	Francisco Bischoff <fbischoff@med.up.pt>
Description:	This is the core functions needed by the 'tsmp' package. The low level and carefully checked mathematical functions are here. These are implementations of the Matrix Profile concept that was created by CS-UCR http://www.cs.ucr.edu/~eamonn/MatrixProfile.html.
License:	GPL-3
URL:	https://matrix-profile-foundation.github.io/matrixprofiler/, https://github.com/matrix-profile-foundation/matrixprofiler
BugReports:	https://github.com/matrix-profile-foundation/matrixprofiler/issues
Depends:	R (≥ 4.1)
Imports:	checkmate (≥ 2.1.0), Rcpp (≥ 1.0.9)
Suggests:	debugme (≥ 1.1.0), spelling (≥ 2.2.0), testthat (≥ 3.1.4)
LinkingTo:	Rcpp (≥ 1.0.9), RcppThread (≥ 2.1.3)
Config/testthat/edition:	3
Config/testthat/parallel:	false
Encoding:	UTF-8
Language:	en-US
LazyData:	true
NeedsCompilation:	yes
SystemRequirements:	GNU make
Config/roxygen2/version:	8.1.0
Packaged:	2026-10-14 03:46:18 UTC; franz
Author:	Francisco Bischoff [aut, cre], Michael Yeh [res, ccp, ctb], Diego Silva [res, ccp, ctb], Yan Zhu [res, ccp, ctb], Hoang Dau [res, ccp, ctb], Michele Linardi [res, ccp, ctb]
Repository:	CRAN
Date/Publication:	2026-10-14 04:20:02 UTC

Contrast Profile Computation

Description

Computes the contrast profile of two (classes of) time series.

Usage

contrast(
  negative_data,
  positive_data,
  window_size,
  positive_matrix = NULL,
  exclusion_zone = 0.5,
  distance = c("euclidean", "pearson"),
  n_workers = 1L,
  progress = TRUE
)

Arguments

Details

Constrast Profile

This algorithm returns the contrast profile of two time series, which shows the position of patters that are similar in the positive data, but at the same time very dissimilar in the negative data. In other words, this means that such a pattern represents well positive data and may be taken as a "signature" of that class. More information can be found in the references.

Value

Returns a list with the contrast_profile, plato, plato_nn, plato_idx, plato_nn_idx, w, ez, euclidean values

References

• R. Mercer, S. Alaee, A. Abdoli, S. Singh, A. Murillo and E. Keogh, "Matrix Profile XXIII: Contrast Profile: A Novel Time Series Primitive that Allows Real World Classification," 2021 IEEE International Conference on Data Mining (ICDM), 2021, pp. 1240-1245, doi: 10.1109/ICDM51629.2021.00151.

Website: http://www.cs.ucr.edu/~eamonn/MatrixProfile.html

Examples

cp <- contrast(motifs_discords_small, rev(motifs_discords_small), 50)

Check if package was compiled with CUDA support

Description

Queries whether matrixprofiler was compiled with NVIDIA CUDA GPU acceleration (MATRIXPROFILER_ENABLE_CUDA=1).

Usage

has_cuda()

Details

By default, matrixprofiler is compiled without CUDA to maintain portability and compliance with CRAN policies, running all algorithms on multi-threaded CPU engines powered by RcppThread.

If an NVIDIA GPU and the CUDA Toolkit are available on the host system, the package can be recompiled with CUDA acceleration for supported algorithms (such as rfcp and mpx) using the helper script inst/cuda/build_cuda_rcpp.sh or by setting the environment variables:

• MATRIXPROFILER_ENABLE_CUDA=1

• MATRIXPROFILER_CUDA_OBJECT pointing to precompiled CUDA object files (.o)

• MATRIXPROFILER_CUDA_LIBS pointing to the CUDA runtime library (e.g. -lcudart)

When has_cuda() returns FALSE, attempting to execute an algorithm with backend = "cuda" will stop with an informative error instructing how to enable CUDA.

Value

A logical value: TRUE if CUDA support was enabled at compile time, FALSE otherwise.

Examples

has_cuda()

Computes the Distance between the 'data' and the 'query'.

Description

This algorithm will use a rolling window, to computes the distance thorough the whole data. This means that the minimum distance found is the motif and the maximum distance is the discord on that time series. Attention you need first to create an object using mass_pre(). Read below.

Usage

mass(
  pre_obj,
  data,
  query = data,
  index = 1,
  version = c("v3", "v2"),
  n_workers = 1
)

mass_pre(
  data,
  window_size,
  query = NULL,
  type = c("normalized", "non_normalized", "absolute", "weighted"),
  weights = NULL
)

Arguments

Details

There are currently four ways to compare the window with the data:

1. normalized: this normalizes the data and the query window. This is the most frequently used.

2. non_normalized: this won't normalize the query window. The data still being normalized.

3. absolute: this won't normalize both the data and the query window.

4. weighted: this normalizes the data and query window, and also apply a weight vector on the query.

Value

mass() returns a list with the distance_profile and the last_product that is only useful for computing the Matrix Profile.

mass_pre() returns a list with several precomputations to be used on MASS later. Attention use this before mass().

Examples

pre <- mass_pre(motifs_discords_small, 50)
dist_profile <- mass(pre, motifs_discords_small)
pre <- mass_pre(motifs_discords_small, 50)
dist_profile <- mass(pre, motifs_discords_small)

Matrix Profile for R

Description

This package is derived from the former package tsmp. It is intended to make a clear separation of what is the Matrix Profile computation and what are the data mining process we can do using Matrix Profile.

Details

The Matrix Profile, has the potential to revolutionize time series data mining because of its generality, versatility, simplicity and scalability. In particular it has implications for time series motif discovery, time series joins, shapelet discovery (classification), density estimation, semantic segmentation, visualization, rule discovery, clustering etc.

Multithreading

This package uses RcppThread for multithreaded computations. Thread counts can be controlled directly via the n_workers argument in each function.

Parallel execution and forked processes

matrixprofiler uses native threads for parallel computation. To parallelize a single computation, use the function's n_workers argument.

Avoid calling package functions from fork-based workers, such as those created by parallel::mclapply(), particularly after multithreaded libraries have been initialized in the parent R session. Forked processes inherit library state that may cause deadlocks or crashes.

Where fork detection is implemented, requesting multiple workers in a forked child triggers a warning and reduces n_workers to 1. This precaution does not make fork-based execution safe, because it cannot undo inherited library state.

To process multiple time series concurrently, prefer a PSOCK cluster, which starts independent R sessions (see parallel::makePSOCKcluster()). Use n_workers = 1 within each worker to avoid excessive thread creation.

This limitation concerns the execution environment and applies to both STOMP and MPX; switching algorithms does not remove it.

References

• Yeh CCM, Zhu Y, Ulanova L, Begum N, Ding Y, Dau HA, et al. Matrix profile I: All pairs similarity joins for time series: A unifying view that includes motifs, discords and shapelets. Proc - IEEE Int Conf Data Mining, ICDM. 2017;1317-22.

• Zhu Y, Imamura m, Nikovski D, Keogh E. Matrix Profile VII: Time Series Chains: A New Primitive for Time Series Data Mining. Knowl Inf Syst. 2018 Jun 2;1-27.

• Zhu Y, Zimmerman Z, Senobari NS, Yeh CM, Funning G. Matrix Profile II : Exploiting a Novel Algorithm and GPUs to Break the One Hundred Million Barrier for Time Series Motifs and Joins. Icdm. 2016 Jan 22;54(1):739-48.

Website: http://www.cs.ucr.edu/~eamonn/MatrixProfile.html

Just a synthetic dataset for testing

Description

Just a synthetic dataset for testing

Usage

motifs_discords_small

Format

A vector with 875 observations

Several moving window functions

Description

These functions compute running window statistics with comprehensive support for missing and non-finite values (NA, NaN, Inf).

Usage

mov_mean(
  data,
  window_size,
  type = c("ogita", "normal", "weighted", "fading"),
  eps = 0.9,
  na_strategy = c("window_na", "remove", "error"),
  na.rm = NULL
)

mov_var(
  data,
  window_size,
  type = c("ogita", "normal", "weighted", "fading"),
  eps = 0.9,
  na_strategy = c("window_na", "remove", "error"),
  na.rm = NULL
)

mov_sum(
  data,
  window_size,
  type = c("ogita", "normal", "weighted", "fading"),
  eps = 0.9,
  na_strategy = c("window_na", "remove", "error"),
  na.rm = NULL
)

mov_max(
  data,
  window_size,
  na_strategy = c("window_na", "remove", "error"),
  na.rm = NULL
)

mov_min(
  data,
  window_size,
  na_strategy = c("window_na", "remove", "error"),
  na.rm = NULL
)

mov_std(
  data,
  window_size,
  rcpp = TRUE,
  na_strategy = c("window_na", "remove", "error"),
  na.rm = NULL
)

movmean_std(
  data,
  window_size,
  rcpp = TRUE,
  na_strategy = c("window_na", "remove", "error"),
  na.rm = NULL
)

muinvn(
  data,
  window_size,
  n_workers = 1L,
  na_strategy = c("window_na", "remove", "error"),
  na.rm = NULL
)

zero_crossing(data, window_size)

Arguments

Details

Some functions may use different algorithms to compute the results. The available types are:

1. ogita: This is the default. It uses the Ogita et al., Accurate Sum, and Dot Product for precision. It is not the fastest algorithm, but the time spent vs. guarantee of precision worth it.

2. normal: This uses the cumsum method that is faster, but unreliable in some situations (I have to find the references, but is true).

3. weighted: This uses Rodrigues P., et al. algorithm that uses a weighted window for online purposes. The eps argument controls the factor. (The function is not online yet)

4. fading: This also uses Rodrigues P., et al. algorithm that in this case, uses a fading factor, also for online purposes. he eps argument controls the factor. (The function is not online yet)

Another important detail is that the standard deviation we use for all computations is the population (i.e.: divided by n), not the sample (i.e.: divided by n - 1). That is why we also provide the internally the ⁠:::std()⁠ function that computes the population, differently from stats::sd() that is the sample kind. Further more, movmean_std() shall be used when you need both results in one computation. This is faster than call mov_mean() followed by mov_std(). Finally, muinvn() is kept like that for historical reasons, as it is the function used by mpx(). It returns the sig (stable inverse centered norm) instead of std (sig is equals to 1 / (std * sqrt(window_size))).

Value

mov_mean() returns a vector with moving avg.

mov_var() returns a vector with moving var.

mov_sum() returns a vector with moving sum.

mov_max() returns a vector with moving max.

mov_min() returns a vector with moving min.

mov_std() returns a vector with moving sd.

movmean_std() returns a list with vectors of the moving avg, sd, sig, sum and sqrsum.

muinvn() returns a list with vectors of moving avg and sig.

zero_crossing() returns a vector of times the data crossed the 'zero' line inside a rolling window.

Examples

mov <- mov_mean(motifs_discords_small, 50)
mov <- mov_var(motifs_discords_small, 50)
mov <- mov_sum(motifs_discords_small, 50)
mov <- mov_max(motifs_discords_small, 50)
mov <- mov_min(motifs_discords_small, 50)
mov <- mov_std(motifs_discords_small, 50)
mov <- movmean_std(motifs_discords_small, 50)
mov <- muinvn(motifs_discords_small, 50)
zero_cross <- zero_crossing(motifs_discords_small, 50)

MPdist - Distance between Time Series using Matrix Profile

Description

MPdist is a distance measure which considers two time series to be similar if they share many similar subsequences, regardless of the order of matching subsequences.

Usage

mpdist(
  ref_data,
  query_data,
  window_size,
  type = c("simple", "vector"),
  thr = 0.05,
  n_workers = 1L
)

Arguments

Value

Returns the distance scalar ("simple") or a numeric vector ("vector").

References

• Gharghabi S, Imani S, Bagnall A, Darvishzadeh A, Keogh E. Matrix Profile XII: MPdist: A Novel Time Series Distance Measure to Allow Data Mining in More Challenging Scenarios. In: 2018 IEEE International Conference on Data Mining (ICDM). 2018.

Website: https://sites.google.com/site/mpdistinfo/

Examples

ref_data <- motifs_discords_small[1:200]
qe_data <- motifs_discords_small[201:400]
w <- 30
deq <- mpdist(ref_data, qe_data, w)

Multivariate STOMP Algorithm

Description

Computes the Matrix Profile and Profile Index for Multivariate Time Series.

Usage

mstomp(
  data,
  window_size,
  exclusion_zone = 0.5,
  must_dim = NULL,
  exc_dim = NULL,
  n_workers = 1L,
  progress = TRUE
)

Arguments

Value

Returns a list with the matrix profile matrix_profile, profile index profile_index, left and right matrix profiles left_matrix_profile, right_matrix_profile and profile indices left_profile_index, right_profile_index, window size w, number of dimensions n_dim, exclusion zone ez, must dimensions must and excluded dimensions exc.

References

• Yeh CM, Kavantzas N, Keogh E. Matrix Profile VI : Meaningful Multidimensional Motif Discovery.

• Zhu Y, Imamura M, Nikovski D, Keogh E. Matrix Profile VII: Time Series Chains: A New Primitive for Time Series Data Mining. Knowl Inf Syst. 2018 Jun 2;1-27.

Website: https://sites.google.com/view/mstamp/

Website: http://www.cs.ucr.edu/~eamonn/MatrixProfile.html

See Also

Other matrix profile computations: stamp()

Examples

mp <- mstomp(motifs_discords_small, 50, progress = FALSE)

Relative Frequency Contrast Profile

Description

Computes an exact, NA-aware Relative Frequency Contrast Profile (RFCP) between a positive series and a negative series. For every valid positive window, RFCP compares ordered non-overlapping neighbor ranks from the positive self-join and the positive-to-negative AB-join.

Usage

rfcp(
  positive_data,
  negative_data,
  window_size,
  max_freq,
  exclusion_radius = NULL,
  query_begin = 1L,
  query_end = NULL,
  return_profiles = FALSE,
  n_workers = 1L,
  progress = TRUE,
  backend = "cpu"
)

Arguments

Details

NA, NaN, Inf, and -Inf are barriers. Windows touching a barrier, constant windows, and otherwise non-normalizable windows cannot be queries or neighbors. Returned neighbor indices are one-based global coordinates. Candidates are ordered by increasing distance and then increasing index. After accepting a neighbor at j, the closed interval ⁠[j - exclusion_radius, j + exclusion_radius]⁠ is excluded. The same neighborhood around the query is excluded before AA selection.

For rank k, distances are clipped at sqrt(2 * window_size) before calculating max((AB - AA) / sqrt(2 * window_size), 0). Missing ranks contribute zero while the RMSC denominator remains the requested max_freq. effective_max_freq is diagnostic: it is the largest number of paired finite AA/AB ranks observed for any completed query and never changes the denominator.

The default mode materializes only the RMSC values for the requested query block and the rank vectors for the selected Plato. Blocks use global query coordinates and can be concatenated for checkpointed execution. With return_profiles = TRUE, RFMP matrices contain unclipped z-normalized Euclidean distances and RFCP contains the corresponding clipped contrasts. Native query tiles use min(32768, max(1024, 16 * window_size)), further capped at the ceiling of the requested query count divided by the effective worker count. The first tile starts at query_begin, so checkpoint blocks do not perform discarded warm-up rows. The CUDA backend executes the full join query-by-query with optional profile matrices returned identically to the CPU backend.

Value

A list with RFCP outputs:

• rms_profile: numeric vector of root-mean-square contrasts.

• valid_window_positive: logical mask of valid query windows.

• valid_window_negative: logical mask of valid reference windows.

• plato_index: one-based index of the highest-contrast query.

• plato_rms: contrast score at plato_index.

• plato_twin_index: one-based index of the nearest self-join neighbor at plato_index.

• rfcp_at_plato: clipped contrasts across accepted neighbor ranks.

• rfmp_aa_at_plato: positive self-join distances at plato.

• rfmp_ab_at_plato: negative AB distances at plato.

• rfmpi_aa_at_plato: positive neighbor indices at plato.

• rfmpi_ab_at_plato: negative neighbor indices at plato.

• requested_max_freq: requested rank count.

• effective_max_freq: highest paired rank observed.

• query_begin, query_end: one-based query range.

• completed_query_end: end of completed queries.

• partial: whether computation stopped early.

• rfmp_aa, rfmp_ab, rfcp, rfmpi_aa, rfmpi_ab: optional full profile matrices when return_profiles = TRUE.

Examples

pos <- c(sin(seq(0, 4 * pi, length.out = 100)))
neg <- c(cos(seq(0, 10 * pi, length.out = 150)))
res <- rfcp(pos, neg, window_size = 10, max_freq = 2)
res$plato_index

Top-K Relative Frequency Contrast Profile

Description

Discovers the top-K contrasting patterns (Platos) between a positive time series and a negative time series using an iterative Relative Frequency Contrast Profile (RFCP) procedure.

Usage

rfcp_top_k(
  positive_data,
  negative_data,
  window_size,
  k_platos = 2L,
  max_freq = 5L,
  exclusion_radius = NULL,
  min_rms = 1e-04,
  adaptive_max_freq = FALSE,
  min_freq = 2L,
  n_workers = 1L,
  backend = "cpu",
  progress = FALSE,
  query_block_size = NULL,
  progress_callback = NULL,
  checkpoint_callback = NULL,
  resume_state = NULL
)

Arguments

Details

In each iteration i \in \{1, \dots, K\}, the algorithm:

1. Executes rfcp using the current augmented negative series and the requested frequency max_freq[i].

2. Identifies the highest-contrast query window (\text{Plato}_i) outside the exclusion zone of previously discovered Platos and their associated neighbors.

3. If the contrast score is below min_rms or no valid candidate remains, iteration terminates early.

4. Extracts the subsequences of \text{Plato}_i and all its accepted positive self-join neighbors (rfmpi_aa_at_plato), expanded by the exclusion zone:

   [\max(1, j - \text{exclusion\_radius}), \min(N^{(+)}, j + \text{window\_size} - 1 + \text{exclusion\_radius})]

5. Merges overlapping intervals to maintain signal continuity, and appends the resulting segments to the negative series separated by NA barriers. Because rfcp is NA-aware, this suppresses the contrast of that morphology and its trivial overlaps in subsequent iterations without introducing spurious cross-boundary windows.

6. If adaptive_max_freq = TRUE, re-evaluates the frequency for the next iteration based on the count of finite AA neighbors with distance below \sqrt{2 \cdot \text{window\_size}}, bounded below by min_freq.

Value

An object of class "rfcp_top_k", which is a list containing:

• k_requested: requested number of Platos.

• k_found: number of Platos discovered before stopping.

• window_size: subsequence length.

• exclusion_radius: exclusion radius used.

• adaptive_max_freq: whether adaptive frequency was enabled.

• min_freq: minimum frequency floor used.

• max_freq: vector of frequencies used for each Plato.

• platos: list of discovered Plato objects, each containing:

  • k: Plato iteration rank (1, 2, ...).

  • plato_index: one-based start index in positive_data.

  • plato_rms: contrast score at plato_index.

  • plato_subsequence: numeric vector containing the pattern.

  • plato_twin_index: one-based start index of nearest self-join neighbor.

  • rfcp_at_plato: clipped contrasts across accepted ranks.

  • rfmp_aa_at_plato: positive self-join distances.

  • rfmp_ab_at_plato: negative AB distances.

  • rfmpi_aa_at_plato: positive neighbor indices.

  • rfmpi_ab_at_plato: negative neighbor indices.

  • effective_max_freq: highest paired rank observed.

• negative_data_final: the negative series augmented with the suppressed Plato occurrences and exclusion zones.

Examples

set.seed(42)
# Create positive series with 5 sine pulses and 2 cosine pulses
t <- seq(0, 4 * pi, length.out = 20)
sine_pulse <- sin(t)
cos_pulse <- cos(t)
pos <- rnorm(300, sd = 0.05)
for (p in c(20, 60, 100, 140, 180)) pos[p:(p + 19)] <- pos[p:(p + 19)] + sine_pulse
for (p in c(220, 260)) pos[p:(p + 19)] <- pos[p:(p + 19)] + cos_pulse * 1.5
neg <- rnorm(300, sd = 0.05)

top_platos <- rfcp_top_k(pos, neg, window_size = 20, k_platos = 2, max_freq = c(4, 2))
print(top_platos)

Matrix Profile Computation

Description

STAMP Computes the best so far Matrix Profile and Profile Index for Univariate Time Series.

STOMP is a faster implementation with the caveat that is not anytime as STAMP or SCRIMP.

SCRIMP is a faster implementation, like STOMP, but has the ability to return anytime results as STAMP.

MPX is by far the fastest implementation with the caveat that is not anytime as STAMP or SCRIMP.

Usage

stamp(
  data,
  window_size,
  query = NULL,
  exclusion_zone = 0.5,
  s_size = 1,
  n_workers = 1,
  progress = TRUE
)

stomp(
  data,
  window_size,
  query = NULL,
  exclusion_zone = 0.5,
  n_workers = 1,
  progress = TRUE,
  left_right_profile = FALSE
)

scrimp(
  data,
  window_size,
  query = NULL,
  exclusion_zone = 0.5,
  s_size = 1,
  pre_scrimp = 0.25,
  n_workers = 1,
  progress = TRUE
)

mpx(
  data,
  window_size,
  query = NULL,
  exclusion_zone = 0.5,
  s_size = 1,
  idxs = TRUE,
  distance = c("euclidean", "pearson"),
  n_workers = 1,
  progress = TRUE,
  na_strategy = c("monolithic", "segmented", "segmented_native"),
  backend = c("cpu", "cuda")
)

mpx_stream_right(
  new_data,
  start_obj,
  history = 0,
  mp_time_constraint = 0,
  progress = TRUE
)

mpx_stream_s_right(
  data,
  batch_size,
  start_obj,
  stats,
  history = 0,
  mp_time_constraint = 0,
  progress = TRUE,
  threshold = -1
)

Arguments

Details

The Matrix Profile, has the potential to revolutionize time series data mining because of its generality, versatility, simplicity and scalability. In particular it has implications for time series motif discovery, time series joins, shapelet discovery (classification), density estimation, semantic segmentation, visualization, rule discovery, clustering etc.

progress, it is really recommended to use it as feedback for long computations. It indeed adds some (neglectable) overhead, but the benefit of knowing that your computer is still computing is much bigger than the seconds you may lose in the final benchmark. Native multithreading uses RcppThread and is controlled by n_workers. See matrixprofiler for guidance on parallel execution across processes and fork limitations. The data and query parameters will be internally converted to a single vector using as.numeric(), thus, bear in mind that a multidimensional matrix may not work as you expect, but most 1-dimensional data types will work normally. If query is provided, expect the same pre-procesment done for data; in addition, exclusion_zone will be ignored and set to 0. Both data and query doesn't need to have the same size and they can be interchanged if both are provided. The difference will be in the returning object. AB-Join returns the Matrix Profile 'A' and 'B' i.e., the distance between a rolling window from query to data and from data to query.

stamp

The anytime STAMP computes the Matrix Profile and Profile Index in such manner that it can be stopped before its complete calculation and return the best so far results allowing ultra-fast approximate solutions.

stomp

The STOMP uses a faster implementation to compute the Matrix Profile and Profile Index. It can be stopped earlier by the user, but the result is not considered anytime, just incomplete. For a anytime algorithm, use stamp() or scrimp().

scrimp

The SCRIMP algorithm was the anytime solution for stomp. It is as fast as stomp but allows the user to cancel the computation and get an approximation of the final result. The exact SCRIMP phase shares the NA-aware diagonal recurrence used by MPX. In serial mode, pre-scrimp first seeds the profile from sampled distance profiles; the multithreaded implementation skips this pre-scrimp stage.

mpx

This algorithm was developed apart from the main Matrix Profile branch that relies on Fast Fourier Transform (FFT) at least in one part of the process. This algorithm doesn't use FFT at all and is several times faster. It also relies on Ogita's work for better precision computing mean and standard deviation (part of the process).

Inputs containing NA, NaN, Inf, or -Inf are automatically routed to the missing-data implementation. Fully finite inputs continue to use the faster regular MPX implementation.

For MPX, values of s_size below 1 select a randomized subset of diagonals and provide the intended anytime approximation. With s_size = 1, all diagonals are processed in monotone order for better locality, so the final result is exact but an interruption before completion can be less representative than a randomized partial run. Use s_size < 1 when an interrupted result should remain an anytime approximation.

The native segmented parallel AA implementation has an optional cache-tuning setting for large NA-aware self-joins. This setting applies only when na_strategy = "segmented_native" selects the native NA-aware parallel path. When s_size = 1, MATRIXPROFILER_NATIVE_AA_BLOCK_SIZE controls the number of profile windows in each rectangular internal block. Its default is 8192; values from 1024 to 262144 are accepted and invalid values fall back to the default. For example, set it for one shell invocation with ⁠MATRIXPROFILER_NATIVE_AA_BLOCK_SIZE=16384 Rscript script.R⁠, or set it in R with Sys.setenv(MATRIXPROFILER_NATIVE_AA_BLOCK_SIZE = "16384") before calling mpx(). Remove the override with Sys.unsetenv("MATRIXPROFILER_NATIVE_AA_BLOCK_SIZE"). The setting is read at call time, does not change the public mpx() API or its numerical parameters, and is ignored for AB joins, finite inputs using regular MPX, and sampled native runs with s_size < 1. It primarily trades cache locality against task overhead; 8192 is a suitable starting point, while larger values should only be selected after benchmarking a substantially larger workload.

The internal C++ target matrix_profile_native_pairs_per_task (currently 100000000 pairwise window comparisons) controls the granularity of native parallel AB tasks and sampled AA tasks. It is used only by the native NA-aware parallel implementation. It is not an mpx() argument or an environment variable; changing it requires a source change and recompiling the package. It is normally left unchanged: increase it only when profiling a very large workload shows excessive scheduling overhead, while retaining several tasks per worker for load balancing. Neither setting affects the regular MPX paths or the serial NA-aware implementations.

Value

Returns a list with the matrix_profile, profile_index (if idxs is TRUE in mpx()), and some information about the settings used to build it, like ez and partial when the algorithm is finished early.

This document

Last updated on 2026-10-14 using R version 4.6.1.

References

• Yeh CCM, Zhu Y, Ulanova L, Begum N, Ding Y, Dau HA, et al. Matrix profile I: All pairs similarity joins for time series: A unifying view that includes motifs, discords and shapelets. Proc - IEEE Int Conf Data Mining, ICDM. 2017;1317-22.

• Zhu Y, Imamura m, Nikovski D, Keogh E. Matrix Profile VII: Time Series Chains: A New Primitive for Time Series Data Mining. Knowl Inf Syst. 2018 Jun 2;1-27.

• Zhu Y, Zimmerman Z, Senobari NS, Yeh CM, Funning G. Matrix Profile II : Exploiting a Novel Algorithm and GPUs to Break the One Hundred Million Barrier for Time Series Motifs and Joins. Icdm. 2016 Jan 22;54(1):739-48.

Website: http://www.cs.ucr.edu/~eamonn/MatrixProfile.html

See Also

mass() for the underlying algorithm that finds best match of a query.

mpxab() for the forward and reverse join-similarity.

Other matrix profile computations: mstomp()

Examples

mp <- stamp(motifs_discords_small, 50)
mp <- stomp(motifs_discords_small, 50)
mp <- scrimp(motifs_discords_small, 50)
mp <- mpx(motifs_discords_small, 50)

Math Functions

Description

znorm(): Normalizes data for mean Zero and Standard Deviation One

ed_corr(): Converts euclidean distances into correlation values

corr_ed(): Converts correlation values into euclidean distances

mode(): Returns the most common value from a vector of integers

std(): Population SD, as R always calculate with n-1 (sample), here we fix it.

normalize(): Normalizes data to be between min and max.

complexity(): Computes the complexity index of the data

binary_split(): Creates a vector with the indexes of binary split.

Usage

znorm(data, rcpp = TRUE)

ed_corr(data, w, rcpp = TRUE)

corr_ed(data, w, rcpp = TRUE)

mode(x, rcpp = FALSE)

std(data, na.rm = FALSE, rcpp = TRUE)

normalize(data, min_lim = 0, max_lim = 1, rcpp = FALSE)

complexity(data)

binary_split(n, rcpp = TRUE)

Arguments

Value

znorm(): Returns the normalized data

ed_corr(): Returns the converted values from euclidean distance to correlation values.

corr_ed(): Returns the converted values from euclidean distance to correlation values.

mode(): Returns the most common value from a vector of integers.

std(): Returns the corrected standard deviation from sample to population.

normalize(): Returns the normalized data between min and max.

complexity(): Returns the complexity index of the data provided (normally a subset).

complexity(): Returns a vector with the binary split indexes.

Examples

normalized <- znorm(motifs_discords_small)
fake_data <- c(rep(3, 100), rep(2, 100), rep(1, 100))
correlation <- ed_corr(fake_data, 50)
fake_data <- c(rep(0.5, 100), rep(1, 100), rep(0.1, 100))
euclidean <- corr_ed(fake_data, 50)
fake_data <- c(1, 1, 4, 5, 2, 3, 1, 7, 9, 4, 5, 2, 3)
mode <- mode(fake_data)
fake_data <- c(1, 1.4, 4.3, 5.1, 2, 3.6, 1.24, 2, 9, 4.3, 5, 2.1, 3)
res <- std(fake_data)
fake_data <- c(1, 1.4, 4.3, 5.1, 2, 3.6, 1.24, 1, 9, 4.3, 5, 2.1, 3)
res <- normalize(fake_data)
fake_data <- c(1, 1.4, 4.3, 5.1, 2, 3.6, 1.24, 8, 9, 4.3, 5, 2.1, 3)
res <- complexity(fake_data)
fake_data <- c(10)
res <- binary_split(fake_data)