ischange
Find abrupt changes in data
Syntax
Description
specifies additional parameters for finding change points using one or more
name-value arguments. For example, TF
= ischange(___,Name,Value
)ischange(A,'MaxNumChanges',m)
detects no more than m
change points.
Examples
Change in Mean
Create a vector of noisy data, and compute the abrupt changes in the mean of the data.
A = [ones(1,5) 25*ones(1,5) 50*ones(1,5)] + rand(1,15); TF = ischange(A)
TF = 1x15 logical array
0 0 0 0 0 1 0 0 0 0 1 0 0 0 0
To compute the mean of the data in between change points, specify a second output argument.
[TF,S1] = ischange(A); plot(A,'*') hold on stairs(S1) legend('Data','Segment Mean','Location','NW')
Change in Linear Regime
Create a vector of noisy data, and compute abrupt changes in the slope and intercept of the data. Setting a large detection threshold reduces the number of change points detected due to noise.
A = [zeros(1,100) 1:100 99:-1:50 50*ones(1,250)] + 10*rand(1,500); [TF,S1,S2] = ischange(A,'linear','Threshold',200); segline = S1.*(1:500) + S2; plot(1:500,A,1:500,segline) legend('Data','Linear Regime')
As an alternative to providing a threshold value, you also can specify the maximum number of change points to detect.
[TF,S1,S2] = ischange(A,'linear','MaxNumChanges',3);
Matrix Data
Compute abrupt changes in the mean for each row of a matrix.
A = diag(25*ones(5,1)) + rand(5,5)
A = 5×5
25.8147 0.0975 0.1576 0.1419 0.6557
0.9058 25.2785 0.9706 0.4218 0.0357
0.1270 0.5469 25.9572 0.9157 0.8491
0.9134 0.9575 0.4854 25.7922 0.9340
0.6324 0.9649 0.8003 0.9595 25.6787
TF = ischange(A,2)
TF = 5x5 logical array
0 1 0 0 0
0 1 1 0 0
0 0 1 1 0
0 0 0 1 1
0 0 0 0 1
Input Arguments
A
— Input data
vector | matrix | multidimensional array | table | timetable
Input data, specified as a vector, matrix, multidimensional array, table, or timetable.
Data Types: single
| double
| table
| timetable
method
— Change detection method
'mean'
(default) | 'variance'
| 'linear'
Change detection method, specified as one of these values:
'mean'
— Find abrupt changes in the mean of the data.'variance'
— Find abrupt changes in the variance of the data.'linear'
— Find abrupt changes in the slope and intercept of the data.
dim
— Operating dimension
positive integer scalar
Operating dimension, specified as a positive integer scalar. If no value is specified, then the default is the first array dimension whose size does not equal 1.
Consider an m
-by-n
input matrix,
A
:
ischange(A,1)
detects change points based on the data in each column ofA
and returns anm
-by-n
matrix.ischange(A,2)
detects change points based on the data in each row ofA
and returns anm
-by-n
matrix.
For table or timetable input data, dim
is not supported
and operation is along each table or timetable variable separately.
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.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: TF = ischange(A,'MaxNumChanges',5)
SamplePoints
— Sample points
vector | table variable name | scalar | function handle | table vartype
subscript
Sample points, specified as a vector of sample point values or one of
the options in the following table when the input data is a table. The
sample points represent the x-axis locations of the
data, and must be sorted and contain unique elements. Sample points do
not need to be uniformly sampled. The vector [1 2 3
...]
is the default.
When the input data is a table, you can specify the sample points as a table variable using one of these options:
Indexing Scheme | Examples |
---|---|
Variable name:
|
|
Variable index:
|
|
Function handle:
|
|
Variable type:
|
|
Note
This name-value argument is not supported when the input data is a
timetable
. Timetables use the vector of row times as the sample
points. To use different sample points, you must edit the timetable so that the row times
contain the desired sample points.
Example: ischange([1 2 3 4 5 6],'linear','SamplePoints',[1 2 3
10 20 30])
Example: ischange(T,'linear','SamplePoints',"Var1")
Data Types: single
| double
| datetime
| duration
DataVariables
— Table variables to operate on
table variable name | scalar | vector | cell array | pattern | function handle | table vartype
subscript
Table variables to operate on, specified as one of the options in this
table. The DataVariables
value indicates which
variables of the input table to examine for change points. The data type
associated with the indicated variables must be
double
or single
.
The first output TF
contains
false
for variables not specified by
DataVariables
unless the value of
OutputFormat
is
'tabular'
.
Indexing Scheme | Examples |
---|---|
Variable names:
|
|
Variable index:
|
|
Function handle:
|
|
Variable type:
|
|
Example: ischange(T,'DataVariables',["Var1" "Var2"
"Var4"])
OutputFormat
— Output data type
'logical'
(default) | 'tabular'
Output data type, specified as one of these values:
'logical'
— For table or timetable input data, return the outputTF
as a logical array.'tabular'
— For table input data, return the outputTF
as a table. For timetable input data, return the outputTF
as a timetable.
For vector, matrix, or multidimensional array input data,
OutputFormat
is not supported.
Example: ischange(T,'OutputFormat','tabular')
Threshold
— Change point threshold
1 (default) | nonnegative scalar
Change point threshold, specified as a nonnegative scalar. Increasing the threshold greater than 1 produces fewer change points.
The threshold value determines the number of detected change points
and cannot be specified when MaxNumChanges
is
specified.
MaxNumChanges
— Maximum number of change points
positive integer scalar
Maximum number of change points to detect, specified as a positive
integer scalar. ischange
uses an automatic threshold
that computes no more than the specified value of change points, thus
Threshold
cannot be specified when
MaxNumChanges
is specified.
Output Arguments
TF
— Change point indicator
vector | matrix | multidimensional array | table | timetable
Change point indicator, returned as a vector, matrix, multidimensional array, table, or timetable.
TF
is the same size as A
unless the
value of OutputFormat
is 'tabular'
. If
the value of OutputFormat
is
'tabular'
, then TF
only has variables
corresponding to the DataVariables
specified.
Data Types: logical
S1
— Mean or slope
vector | matrix | multidimensional array | table | timetable
Mean or slope of data between change points, returned as a vector, matrix, multidimensional array, table, or timetable.
If the change point detection method is
'mean'
or'variance'
, thenS1
contains the mean for each segment.If the method is
'linear'
, thenS1
contains the slope for each segment.
S1
has the same type as the input data.
Data Types: double
| single
| table
| timetable
S2
— Variance or intercept
vector | matrix | multidimensional array | table | timetable
Variance or intercept of data between change points, returned as a vector, matrix, multidimensional array, table, or timetable.
If the change point detection method is
'mean'
or'variance'
, thenS2
contains the variance for each segment.If the method is
'linear'
, thenS2
contains the intercept for each segment.
S2
has the same type as the input data.
Data Types: double
| single
| table
| timetable
More About
Change Points
A vector of data A contains a change point if it can be split into two segments A1 and A2 such that
is the threshold value specified by the
Threshold
parameter, and C represents a
cost function.
For example, the cost function for detecting abrupt changes in the mean is , where N is the number of elements in a vector x. The cost function measures how well a segment is approximated by its mean.
ischange
iteratively minimizes the sum of the cost functions to
determine the number of change points k and their locations such
that
References
[1] Killick R., P. Fearnhead, and I.A. Eckley. "Optimal detection of changepoints with a linear computational cost." Journal of the American Statistical Association. Vol. 107, Number 500, 2012, pp.1590-1598.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
The
OutputFormat
name-value argument is not supported.For single-precision inputs, the output of the generated code might not match the MATLAB® output. This is because the generated code for
ischange
executes most intermediate computations in single precision.DataVariables
must not contain duplicate variable names.
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.
Version History
Introduced in R2017bR2022a: Return table or timetable containing logical output
For table or timetable input data, return a tabular output TF
instead
of a logical array by setting the OutputFormat
name-value argument to
'tabular'
.
R2021b: Specify sample points as table variable
For table input data, specify the sample points as a table variable using the
SamplePoints
name-value argument.
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)