Main Content

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=5×2 cell array
    {[ 1 4 8 27 32 45 47 2 35 37 41 6 17 12 36 3 7 10 26 33 38 46 39 40 19 9 31]}    {[ 1 4 8 27 32 45 47 2 35 37 41 6 17 12 36 3 7 10 26 33 38 46 39 40 19 9 31]}
    {[                                                                       13]}    {[                                                                       13]}
    {[6 17 39 40 1 4 8 27 32 45 47 19 2 35 37 41 16 3 7 10 26 33 38 46 15 21 30]}    {[6 17 39 40 1 4 8 27 32 45 47 19 2 35 37 41 16 3 7 10 26 33 38 46 15 21 30]}
    {[                                                                    64 66]}    {[                                                                    64 66]}
    {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=5×1 cell array
    {[26 38 7 17 47 4 27 46 25 10 39 20 21 2 33]}
    {[                             6 21 25 4 19]}
    {[                          1 34 33 22 24 2]}
    {[                                       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、または hnswSearcher モデル オブジェクトとして指定します。

Mdl が ExhaustiveSearcher モデルの場合、rangesearch は網羅的探索を使用して最近傍を探索します。Mdl が KDTreeSearcher モデルの場合、rangesearch は成長した Kd 木を使用して最近傍を探索します。Mdl が hnswSearcher モデルの場合、rangesearch は Hierarchical Navigable Small Worlds 近似最近傍探索アルゴリズムを使用します。詳細については、k 最近傍探索および半径探索を参照してください。

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

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

データ型: single | double

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

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

データ型: single | double

名前と値の引数

オプションの引数のペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名、Value は対応する値です。名前と値の引数は他の引数の後ろにする必要がありますが、ペアの順序は関係ありません。

R2021a より前では、名前と値をそれぞれコンマを使って区切り、Name を引用符で囲みます。

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

両方の最近傍探索モデル

すべて折りたたむ

クエリ観測値に対する学習データの近傍を求めるために使用する距離計量。次の表の値のいずれか、または関数ハンドルとして指定します。

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

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

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

値説明
'correlation'1 から、観測値間の標本線形相関を減算 (値の系列として処理)
'cosine'(行ベクトルとして扱われる) 観測値間の夾角の余弦を 1 から減算
'fasteuclidean'予測子の数が 10 個以上の場合に時間の短縮になる代替アルゴリズムを使用して計算されるユークリッド距離。このアルゴリズムは高速ですが、場合によっては精度が低下することがあります。この距離計量は、NSMethod が 'exhaustive' の場合にのみ使用できます。'fast' から始まるアルゴリズムでは、スパース データはサポートされません。詳細については、アルゴリズムを参照してください。
'fastseuclidean'予測子の数が 10 個以上の場合に時間の短縮になる代替アルゴリズムを使用して計算される標準化されたユークリッド距離。このアルゴリズムは高速ですが、場合によっては精度が低下することがあります。この距離計量は、NSMethod が 'exhaustive' の場合にのみ使用できます。'fast' から始まるアルゴリズムでは、スパース データはサポートされません。詳細については、アルゴリズムを参照してください。
'hamming'ハミング距離 (異なる座標の比率)
'jaccard'1 からジャカード係数 (異なる非ゼロ座標の比率) を減算
'mahalanobis'正定値共分散行列を使用して計算されるマハラノビス距離。共分散行列の値を変更するには、名前と値の引数 'Cov' を使用します。
'seuclidean'標準化されたユークリッド距離。X の行とクエリ行列 Y の行の間の各座標差は、X から算出される標準偏差の対応する要素で除算することによりスケーリングされます。別のスケーリングを指定するには、名前と値の引数 'Scale' を使用します。
'spearman'1 から観測値間の標本スピアマン順位相関係数を減算 (値の系列として処理)

Mdl が hnswSearcher モデル オブジェクトの場合、rangesearch は ExhaustiveSearcher の表にある距離を fast から始まる "fasteuclidean" と "fastseuclidean" を除いてすべてサポートします。

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'

データ型: char | string | function_handle

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

P の値により、モデル オブジェクトの DistParameter プロパティの値が設定されます。

例: 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 で導入

参考

| | | |

トピック