This is machine translation

Translated by Microsoft
Mouse over text to see original. Click the button below to return to the English verison of the page.


Create object to use in k-nearest neighbors search


NS = createns(X)
NS = createns(X,'Name',Value)


NS = createns(X) uses the data observations in an mx-by-n matrix X to create an object NS. Rows of X correspond to observations and columns correspond to variables. NS is either an ExhaustiveSearcher or a KDTreeSearcher model object which you can use to find nearest neighbors in X for desired query points. If NS is an ExhaustiveSearcher model, knnsearch and rangesearch use the exhaustive search algorithm to find nearest neighbors. If NS is a KDTreeSearcher model, createns grows and saves a Kd-tree based on X in NS. knnsearch and rangesearch use the Kd-tree to find nearest neighbors. For information on these search methods, see k-Nearest Neighbor Search and Radius Search.

NS = createns(X,'Name',Value) accepts one or more optional name/value pairs. Specify Name inside single quotes. Specify NSMethod to determine which type of object to create. The object's properties save the information when you specify other arguments. For more information on the objects' properties, see ExhaustiveSearcher or a KDTreeSearcher.

Input Arguments

Name-Value Pair Arguments


Nearest neighbors search method, used to define the type of object created. Value is either:

  • 'kdtree' — Create a KDTreeSearcher model. If you do not specify NSMethod, this is the default value when the number of columns of X is less than 10, X is not sparse, and the distance measure is one of the following measures:

    • 'euclidean' (default)

    • 'cityblock'

    • 'minkowski'

    • 'chebychev'

  • 'exhaustive' — Create an ExhaustiveSearcher model. If you do not specify NSMethod, this is the default value when the default criteria for 'kdtree' do not apply.


A character vector or a function handle specifying the default distance metric used when you call knnsearch or rangesearch to find nearest neighbors for future query points. If you specify a distance metric but not an NSMethod, this input determines the type of object createns creates, according to the default values described in NSMethod.

For both KDTreeSearcher and ExhaustiveSearcher models, the following options apply:

  • 'euclidean' (default) — Euclidean distance.

  • 'cityblock' — City block distance.

  • 'chebychev' — Chebychev distance (maximum coordinate difference).

  • 'minkowski' — Minkowski distance.

The following options apply to ExhaustiveSearcher models:

  • 'seuclidean' — Standardized Euclidean distance. Each coordinate difference between rows in X and the query matrix is scaled by dividing by the corresponding element of the standard deviation computed from X, S=nanstd(X). To specify another value for S, use the Scale argument.

  • 'mahalanobis' — Mahalanobis distance, which is computed using a positive definite covariance matrix C. The default value of C is the sample covariance matrix of X, as computed by nancov(X). To change the value of C, use the Cov parameter.

  • 'cosine' — One minus the cosine of the included angle between observations (treated as vectors).

  • '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 percentage of coordinates that differ.

  • 'jaccard' — One minus the Jaccard coefficient, which is the percentage of nonzero coordinates that differ.

  • custom distance function — A distance function specified using @ (for example, @distfun). A distance function must be of the form function D2 = distfun(ZI, ZJ), taking as arguments a 1-by-n vector ZI containing a single row from X or from the query points Y, and an m2-by-n matrix ZJ containing multiple rows of X or Y, and returning an m2-by-1 vector of distances d2, whose jth element is the distance between the observations ZI and ZJ(j,:).


A positive scalar, p, indicating the exponent of the Minkowski distance. This parameter is only valid when Distance is 'minkowski'. Default is 2.


A positive definite matrix indicating the covariance matrix when computing the Mahalanobis distance. This parameter is only valid when Distance is 'mahalanobis'. Default is nancov(X).


A vector S with the length equal to the number of columns in X. Each coordinate of X and each query point is scaled by the corresponding element of S when computing the standardized Euclidean distance. This parameter is only valid when Distance is 'seuclidean'. Default is nanstd(X).


A positive integer, indicating the maximum number of data points in each leaf node of the Kd-tree. This argument is only meaningful when using the Kd-tree search method. Default is 50.


collapse all

Grow a K d-tree that uses the Minkowski distance with an exponent of five.

Load Fisher's iris data set. Create a variable for the petal dimensions.

load fisheriris
x = meas(:,3:4);

Grow a K d-tree. Specify the Minkowski distance with an exponent of five.

Mdl = createns(x,'Distance','minkowski','P',5)
Mdl = 

  KDTreeSearcher with properties:

       BucketSize: 50
         Distance: 'minkowski'
    DistParameter: 5
                X: [150×2 double]

Since x has two columns and the distance metric is Minkowski, createns creates a KDTreeSearcher model by default.

Introduced in R2010a

Was this topic helpful?