ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

rangesearch

探索モデル オブジェクトを使用して指定距離内の近傍をすべて探索

ページ内をすべて折りたたむ

構文

Idx = rangesearch(Mdl,Y,r)
Idx = rangesearch(Mdl,Y,r,Name,Value)
[Idx,D] = rangesearch(___)

説明

例

Idx = rangesearch(Mdl,Y,r) は、網羅的探索または Kd 木を使用して、クエリ データ Y 内の各点 (行または観測値) から半径 r 以内にあるすべての近傍 (点、行または観測値) を Mdl.X から探索します。rangesearch が返す Idx は、r 単位以内にある Mdl.X のインデックスが含まれている列ベクトルです。

例

Idx = rangesearch(Mdl,Y,r,Name,Value) は、1 つ以上の Name,Value ペア引数で指定された追加オプションを使用して、Y 内の各観測値から半径 r 以内にある Mdl.X 内の観測値のインデックスを返します。たとえば、Mdl.Distance に格納されているものとは異なる距離計量や Mdl.DistParameter に格納されているものとは異なる距離計量パラメーターを使用するように指定できます。

例

[Idx,D] = rangesearch(___) は、前の構文の入力引数のいずれかを使用して、さらに行列 D を返します。D には、Y 内の各観測値と半径 r 以内にある Mdl.X 内の観測値の距離が格納されます。既定では、D の列は、距離計量による近さの昇順で並べ替えられます。

例

すべて折りたたむ

ライブ スクリプトを開く

rangesearch は、ExhaustiveSearcher または KDTreeSearcher モデル オブジェクトを受け入れて、クエリ データに対する最近傍を学習データから探索します。ExhaustiveSearcher モデルは、網羅的探索アルゴリズムを呼び出します。KDTreeSearcher モデルは、rangesearch で最近傍の探索に使用される Kd 木を定義します。

フィッシャーのアヤメのデータセットを読み込みます。クエリ データ用に 5 つの観測値をデータから無作為に抽出します。花弁の寸法に焦点を当てます。

load fisheriris
rng(1); % For reproducibility
n = size(meas,1);
idx = randsample(n,5);
X = meas(~ismember(1:n,idx),3:4); % Training data
Y = meas(idx,3:4);                % Query data

既定の 2 次元 Kd 木を成長させます。

MdlKDT = KDTreeSearcher(X)
MdlKDT = 
  KDTreeSearcher with properties:

       BucketSize: 50
         Distance: 'euclidean'
    DistParameter: []
                X: [145x2 double]

MdlKDT は KDTreeSearcher モデル オブジェクトです。書き込み可能なプロパティは、ドット表記を使用して変更できます。

網羅的最近傍探索モデルを準備します。

MdlES = ExhaustiveSearcher(X)
MdlES = 
  ExhaustiveSearcher with properties:

         Distance: 'euclidean'
    DistParameter: []
                X: [145x2 double]

MdlES は ExhaustiveSearcher モデル オブジェクトです。このオブジェクトには、最近傍の探索に使用する距離計量などのオプションが格納されています。

Kd 木の成長と網羅的最近傍探索モデルの準備には、createns も使用できます。

各クエリ観測値から半径 0.5 cm 以内にある最近傍のインデックスを学習データから探索します。両方のタイプの探索を実行し、既定の設定を使用します。

r = 0.15; % Search radius
IdxKDT = rangesearch(MdlKDT,Y,r);
IdxES = rangesearch(MdlES,Y,r);
[IdxKDT IdxES]
ans = 5x2 cell array
    {1x27 double}    {1x27 double}
    {[       13]}    {[       13]}
    {1x27 double}    {1x27 double}
    {1x2  double}    {1x2  double}
    {1x0  double}    {1x0  double}

IdxKDT と IdxES は、Y 内の観測値から 0.15 cm 以内にある X のインデックスに対応するベクトルの cell 配列です。このインデックス行列の各行は、クエリ観測値に対応します。

これらの方法の結果を比較します。

cellfun(@isequal,IdxKDT,IdxES)
ans = 5x1 logical array

   1
   1
   1
   1
   1

この場合、結果は同じです。

setosa 種のアヤメについて結果をプロットします。

setosaIdx = strcmp(species(~ismember(1:n,idx)),'setosa');
XSetosa = X(setosaIdx,:);
ySetosaIdx = strcmp(species(idx),'setosa');
YSetosa = Y(ySetosaIdx,:);

figure;
plot(XSetosa(:,1),XSetosa(:,2),'.k');
hold on;
plot(YSetosa(:,1),YSetosa(:,2),'*r');
for j = 1:sum(ySetosaIdx)
    c = YSetosa(j,:);
    circleFun = @(x1,x2)r^2 - (x1 - c(1)).^2 - (x2 - c(2)).^2;
    fimplicit(circleFun,[c(1) + [-1 1]*r, c(2) + [-1 1]*r],'b-')
end
xlabel 'Petal length (cm)';
ylabel 'Petal width (cm)';
title 'Setosa Petal Measurements';
legend('Observations','Query Data','Search Radius');
axis equal
hold off

ライブ スクリプトを開く

フィッシャーのアヤメのデータセットを読み込みます。

load fisheriris

クエリ セットとして使用するため、5 つのアヤメのデータを無作為に予測子データから抽出します。

rng(1);                     % For reproducibility
n = size(meas,1);           % Sample size
qIdx = randsample(n,5);     % Indices of query data
X = meas(~ismember(1:n,qIdx),:);
Y = meas(qIdx,:);

既定の網羅的最近傍探索モデルを準備します。

Mdl = ExhaustiveSearcher(X)
Mdl = 
  ExhaustiveSearcher with properties:

         Distance: 'euclidean'
    DistParameter: []
                X: [145x4 double]

Mdl は ExhaustiveSearcher モデルです。

求める学習データ (X) のインデックスは、クエリ データ (Y) の各点から 0.15 cm 以内にあります。距離の尺度としてマハラノビス距離を指定します。

r = 1;
Idx = rangesearch(Mdl,Y,r,'Distance','mahalanobis')
Idx = 5x1 cell array
    {1x15 double}
    {1x5  double}
    {1x6  double}
    {[       84]}
    {[       69]}


Idx{3}
ans = 1×6

     1    34    33    22    24     2

Idx の各セルはクエリ データの観測値に対応しており、 クエリ データから 0.15 cm 以内にある X には、近傍のインデックスで構成されるベクトルが含まれています。rangesearch では、インデックスを距離の昇順で並べ替えます。たとえば、マハラノビス距離を使用すると、Y(3,:) の 2 番目の最近傍は X(34,:) になります。

ライブ スクリプトを開く

フィッシャーのアヤメのデータセットを読み込みます。

load fisheriris

クエリ セットとして使用するため、5 つのアヤメのデータを無作為に予測子データから抽出します。

rng(4);                     % For reproducibility
n = size(meas,1);           % Sample size
qIdx = randsample(n,5);     % Indices of query data
X = meas(~ismember(1:n,qIdx),:);
Y = meas(qIdx,:);

学習データを使用して 4 次元の Kd 木を成長させます。最近傍の探索にミンコフスキー距離を使用するよう指定します。

Mdl = KDTreeSearcher(X);

Mdl は KDTreeSearcher モデルです。既定の設定では、最近傍を探索するための距離計量はユークリッド尺度です。

求める学習データ (X) のインデックスは、クエリ データ (Y) の各点から 0.5 cm 以内にあります。

r = 0.5;
[Idx,D] = rangesearch(Mdl,Y,r);

Idx と D は 5 要素の cell 配列で、ベクトルが含まれています。Idx のベクトルの値は、X のインデックスです。X のインデックスは、クエリ データ Y から 0.5 cm 以内にある観測値を表します。D には、観測値に対応する距離が格納されます。

クエリ観測値 3 について結果を表示します。

Idx{3}
ans = 1×2

   127   122


D{3}
ans = 1×2

    0.2646    0.4359

Y(3,:) に最も近い観測値は X(127,:) で、0.2646 cm 離れています。次に近いのは X(122,:) で、0.4359 cm 離れています。他のすべての観測値は、Y(5,:) から 0.5 cm 以上離れています。

入力引数

すべて折りたたむ

最近傍探索モデル。ExhaustiveSearcher または KDTreeSearcher モデル オブジェクトを指定します。

Mdl が ExhaustiveSearcher モデルの場合、rangesearch は網羅的探索を使用して最近傍を探索します。それ以外の場合、rangesearch は成長した Kd 木を使用して最近傍を探索します。

クエリ データ。数値行列を指定します。

Y は、m 行 K 列の行列です。Y の各行は観測値 (事例) に、各列は予測子 (変数または特徴量) に対応します。Y の列数は、Mdl.X に格納されている学習データの列数と同じでなければなりません。

データ型: single | double

クエリ データの各点に対する探索半径。非負のスカラー値を指定します。

rangesearch は、Y 内の観測値から r 以内の距離にあるすべての観測値を Mdl.X から探索します。Mdl.Distance プロパティには距離が格納されます。

データ型: single | double

名前と値のペアの引数

オプションの Name,Value 引数のコンマ区切りペアを指定します。Name は引数名で、Value は対応する値です。Name は引用符で囲まなければなりません。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を、任意の順番で指定できます。

例: 'Distance','minkowski','P',3 は、指数が 3 のミンコフスキー距離計量を使用して、Y 内の各観測値から r 以内の距離にあるすべての観測値を Mdl.X から探索するように指定します。

両方の最近傍探索モデル

すべて折りたたむ

クエリ観測値に対する学習データの近傍を求めるために使用する距離計量。'Distance' と文字ベクトル、string スカラー、または関数ハンドルから構成されるコンマ区切りのペアとして指定します。

両方のタイプの最近傍探索モデルについて、rangesearch は次の距離計量をサポートします。

値説明
'chebychev'チェビシェフ距離 (最大座標差)。
'cityblock'市街地距離。
'euclidean'ユークリッド距離。
'minkowski'ミンコフスキー距離。既定の指数は 2 です。異なる指数を指定するには、名前と値のペアの引数 'P' を使用します。

Mdl が ExhaustiveSearcher モデル オブジェクトである場合、rangesearch は次の距離計量もサポートします。

値説明
'correlation'1 から、一連の値として扱われる観測間の標本線形相関係数を引きます。
'cosine'(行ベクトルとして扱われる) 観測値間の夾角の余弦を 1 から減算します。
'hamming'異なる座標の比率を示すハミング距離。
'jaccard'1 から、ジャカード係数 (異なる非ゼロ座標の比率) を引いた値。
'mahalanobis'正定共分散行列を使用して計算されるマハラノビス距離。共分散行列の値を変更するには、名前と値のペアの引数 'Cov' を使用します。
'seuclidean'標準化されたユークリッド距離。Mdl.X の行とクエリ行列の行の間の各座標差は、Mdl.X から計算される、対応する標準偏差の要素で除算することによりスケーリングされます。他のスケーリングを指定するには、名前と値のペアの引数 'Scale' を使用します。
'spearman'1 から、観測値間の標本スピアマンの順位相関 (値の系列として扱われる) を引いた値。

Mdl が ExhaustiveSearcher モデル オブジェクトである場合、@ を使用してカスタム距離計量の関数ハンドル (たとえば @distfun) を指定することもできます。カスタム距離関数は、次のようになっていなければなりません。

  • function D2 = distfun(ZI,ZJ) という形式になっている。

  • 次の引数を受け入れる。

    • Mdl.X または Y の 1 行が含まれている 1 行 K 列のベクトル ZI。K は Mdl.X の列数です。

    • Mdl.X または Y の複数行が含まれている m 行 K 列の行列 ZJ。m は正の整数です。

  • m 行 1 列の距離のベクトル D2 を返す。D2(j) は、観測値 ZI と ZJ(j,:) の間の距離です。

詳細は、距離計量を参照してください。

例: 'Distance','minkowski'

ミンコフスキー距離計量の指数。'P' と正のスカラー値をコンマで区切って指定します。この引数は、'Distance' が 'minkowski' である場合のみ有効です。

例: 'P',3

データ型: single | double

返されたインデックスを距離に従って並べ替えるためのフラグ。'SortIndices' と true (1) または false (0) から構成されるコンマ区切りのペアとして指定します。

多数の最近傍がある観測値が多数 Y に含まれている場合、SortIndices を false に設定すると速度を向上させることができます。この場合、rangesearch が返す最近傍点のインデックスに特定の順序はありません。SortIndices が true である場合、最近傍点のインデックスは距離の昇順で並べ替えられます。

例: 'SortIndices',false

データ型: logical

網羅的最近傍探索モデルの場合

すべて折りたたむ

マハラノビス距離計量の共分散行列。'Cov' と正定行列をコンマ区切りのペアとして指定します。Cov は K 行 K 列の行列で、K は Mdl.X の列数です。Cov を指定して 'Distance','mahalanobis' を指定しなかった場合、rangesearch はエラー メッセージを返します。

例: 'Cov',eye(3)

データ型: single | double

標準化されたユークリッド距離計量のスケール パラメーター値。'Scale' と非負の数値ベクトルから構成されるコンマ区切りのペアとして指定します。Scale の長さは K です。K は Mdl.X の列数です。

学習データとクエリ データの間の距離は、対応する Scale の要素を使用してスケーリングされます。Scale を指定して 'Distance','seuclidean' を指定しなかった場合、rangesearch はエラー メッセージを返します。

例: 'Scale',quantile(Mdl.X,0.75) - quantile(Mdl.X,0.25)

データ型: single | double

メモ

'Distance'、'Cov'、'P' または 'Scale' を指定した場合、Mdl.Distance と Mdl.DistParameter の値は変更されません。

出力引数

すべて折りたたむ

最近傍の学習データのインデックス。数値ベクトルの cell 配列として返されます。

Idx は m 行 1 列の cell 配列であり、クエリ観測値 Y(j,:) からの距離が r 単位以内である Mdl.X 内の観測値のインデックスによる mj 次元ベクトルが cell j (Idx{j}) に格納されます。SortIndices が true である場合、rangesearch はこのベクトルの要素を距離の昇順で並べ替えます。

クエリ データに対する近傍の距離。数値行列または数値ベクトルの cell 配列として返されます。

D は m 行 1 列の cell 配列です。セル j (D{j}) には mj 次元ベクトルが格納され、このベクトルには Mdl.X 内の観測値とクエリ観測値 Y(j,:) の距離が格納されます。このベクトルの要素はすべて r より小さくなります。SortIndices が true である場合、rangesearch はこのベクトルの要素を昇順で並べ替えます。

ヒント

knnsearch は、Y の各点についての k 最近傍である k (正の整数) 個の点を Mdl.X 内で探索します。これに対して rangesearch は、Y の各点に対する距離が r (正のスカラー) 以内であるすべての点を Mdl.X 内で探索します。

代替機能

rangesearch は、ExhaustiveSearcher または KDTreeSearcher モデル オブジェクト、クエリ データおよび距離を必要とするオブジェクト関数です。同じ条件の場合、名前と値のペアの引数 'NSMethod','exhaustive' または 'NSMethod','kdtree' を指定すると、rangesearch は rangesearch と同じ結果を返します。

拡張機能

参考

| | | |

トピック

R2011b で導入

Statistics and Machine Learning Toolbox ドキュメンテーション
サポート
機械学習をマスターする: MATLAB ステップ・バイ・ステップ ガイド

機械学習をマスターする: MATLAB ステップ・バイ・ステップ ガイド

ebookをダウンロードする