Statistics: rangesearch

Function Reference: `rangesearch`

statistics: idx = rangesearch (X, Y, r)
statistics: [idx, D] = rangesearch (X, Y, r)
statistics: […] = rangesearch (…, name, value)

Find all neighbors within specified distance from input data.

idx = rangesearch (X, Y, r) returns all the points in X that are within distance r from the points in Y. X must be an $N×P$ numeric matrix of input data, where rows correspond to observations and columns correspond to features or variables. Y is an $M×P$ numeric matrix with query points, which must have the same numbers of column as X. r must be a nonnegative scalar value. idx is an $M×1$ cell array, where $M$ is the number of observations in Y. The vector Idx{j} contains the indices of observations (rows) in X whose distances to Y(j,:) are not greater than r.

[idx, D] = rangesearch (X, Y, r) also returns the distances, D, which correspond to the points in X that are within distance r from the points in Y. D is an $M×1$ cell array, where $M$ is the number of observations in Y. The vector D{j} contains the indices of observations (rows) in X whose distances to Y(j,:) are not greater than r.

Additional parameters can be specified by Name-Value pair arguments.

`Name`		`Value`
`"P"`		is the Minkowski distance exponent and it must be a positive scalar. This argument is only valid when the selected distance metric is `"minkowski"`. By default it is 2.
`"Scale"`		is the scale parameter for the standardized Euclidean distance and it must be a nonnegative numeric vector of equal length to the number of columns in `X`. This argument is only valid when the selected distance metric is `"seuclidean"`, in which case each coordinate of `X` is scaled by the corresponding element of `"scale"`, as is each query point in `Y`. By default, the scale parameter is the standard deviation of each coordinate in `X`.
`"Cov"`		is the covariance matrix for computing the mahalanobis distance and it must be a positive definite matrix matching the the number of columns in `X`. This argument is only valid when the selected distance metric is `"mahalanobis"`.
`"BucketSize"`		is the maximum number of data points in the leaf node of the Kd-tree and it must be a positive integer. This argument is only valid when the selected search method is `"kdtree"`.
`"SortIndices"`		is a boolean flag to sort the returned indices in ascending order by distance and it is `true` by default. When the selected search method is `"exhaustive"` or the `"IncludeTies"` flag is true, `rangesearch` always sorts the returned indices.
`"Distance"`		is the distance metric used by `rangesearch` as specified below:

	`"euclidean"`	Euclidean distance.
	`"seuclidean"`	standardized Euclidean distance. Each coordinate difference between the rows in `X` and the query matrix `Y` is scaled by dividing by the corresponding element of the standard deviation computed from `X`. To specify a different scaling, use the `"Scale"` name-value argument.
	`"cityblock"`	City block distance.
	`"chebychev"`	Chebychev distance (maximum coordinate difference).
	`"minkowski"`	Minkowski distance. The default exponent is 2. To specify a different exponent, use the `"P"` name-value argument.
	`"mahalanobis"`	Mahalanobis distance, computed using a positive definite covariance matrix. To change the value of the covariance matrix, use the `"Cov"` name-value argument.
	`"cosine"`	Cosine distance.
	`"correlation"`	One minus the sample linear correlation between observations (treated as sequences of values).
	`"spearman"`	One minus the sample Spearman’s rank correlation between observations (treated as sequences of values).
	`"hamming"`	Hamming distance, which is the percentage of coordinates that differ.
	`"jaccard"`	One minus the Jaccard coefficient, which is the percentage of nonzero coordinates that differ.
	`@distfun`	Custom distance function handle. A distance function of the form `function D2 = distfun (XI, YI)`, where `XI` is a $1×P$ vector containing a single observation in $P$ -dimensional space, `YI` is an $N×P$ matrix containing an arbitrary number of observations in the same $P$ -dimensional space, and `D2` is an $N×P$ vector of distances, where `(D2k)` is the distance between observations `XI` and `(YIk,:)`.

"NSMethod" is the nearest neighbor search method used by rangesearch as specified below.

	`"kdtree"`	Creates and uses a Kd-tree to find nearest neighbors. `"kdtree"` is the default value when the number of columns in `X` is less than or equal to 10, `X` is not sparse, and the distance metric is `"euclidean"`, `"cityblock"`, `"manhattan"`, `"chebychev"`, or `"minkowski"`. Otherwise, the default value is `"exhaustive"`. This argument is only valid when the distance metric is one of the four aforementioned metrics.
	`"exhaustive"`	Uses the exhaustive search algorithm by computing the distance values from all the points in `X` to each point in `Y`.

See also: knnsearch, pdist2

Source Code: rangesearch

Example: 1


 ## Generate 1000 random 2D points from each of five distinct multivariate
 ## normal distributions that form five separate classes
 N = 1000;
 d = 10;
 randn ("seed", 5);
 X1 = mvnrnd (d * [0, 0], eye (2), 1000);
 randn ("seed", 6);
 X2 = mvnrnd (d * [1, 1], eye (2), 1000);
 randn ("seed", 7);
 X3 = mvnrnd (d * [-1, -1], eye (2), 1000);
 randn ("seed", 8);
 X4 = mvnrnd (d * [1, -1], eye (2), 1000);
 randn ("seed", 8);
 X5 = mvnrnd (d * [-1, 1], eye (2), 1000);
 X = [X1; X2; X3; X4; X5];

 ## For each point in X, find the points in X that are within a radius d
 ## away from the points in X.
 Idx = rangesearch (X, X, d, "NSMethod", "exhaustive");

 ## Select the first point in X (corresponding to the first class) and find
 ## its nearest neighbors within the radius d.  Display these points in
 ## one color and the remaining points in a different color.
 x = X(1,:);
 nearestPoints = X (Idx{1},:);
 nonNearestIdx = true (size (X, 1), 1);
 nonNearestIdx(Idx{1}) = false;

 scatter (X(nonNearestIdx,1), X(nonNearestIdx,2))
 hold on
 scatter (nearestPoints(:,1),nearestPoints(:,2))
 scatter (x(1), x(2), "black", "filled")
 hold off

 ## Select the last point in X (corresponding to the fifth class) and find
 ## its nearest neighbors within the radius d.  Display these points in
 ## one color and the remaining points in a different color.
 x = X(end,:);
 nearestPoints = X (Idx{1},:);
 nonNearestIdx = true (size (X, 1), 1);
 nonNearestIdx(Idx{1}) = false;

 figure
 scatter (X(nonNearestIdx,1), X(nonNearestIdx,2))
 hold on
 scatter (nearestPoints(:,1),nearestPoints(:,2))
 scatter (x(1), x(2), "black", "filled")
 hold off

Function Reference: rangesearch

Example: 1

Function Reference: `rangesearch`