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

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 の列は、距離計量による近さの昇順で並べ替えられます。

例

Kd 木および網羅的探索による一定半径内の近傍の探索

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;
    ezplot(circleFun,[c(1) + [-1 1]*r, c(2) + [-1 1]*r])
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 以上離れています。

入力引数

Mdl — 最近傍探索モデル

ExhaustiveSearcher モデル オブジェクト | KDTreeSearcher モデル オブジェクト

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

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

Y — クエリ データ

数値行列

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

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

データ型: single | double

r — 探索半径

非負のスカラー

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

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' — 距離計量

Mdl.Distance (既定値) | 'cityblock' | 'euclidean' | 'mahalanobis' | 'minkowski' | 'seuclidean' | 関数ハンドル | ...

クエリ観測値に対する学習データの近傍を求めるために使用する距離計量。'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' — ミンコフスキー距離計量の指数

2 (既定値) | 正のスカラー

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

例: 'P',3

データ型: single | double

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

'Cov' — マハラノビス距離計量の共分散行列

nancov(Mdl.X) (既定値) | 正定行列

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

例: 'Cov',eye(3)

データ型: single | double

'Scale' — 標準化されたユークリッド距離計量のスケール パラメーター値

nanstd(Mdl.X) (既定値) | 非負の数値ベクトル

標準化されたユークリッド距離計量のスケール パラメーター値。'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 の値は変更されません。

出力引数

Idx — 最近傍の学習データのインデックス

数値ベクトルの cell 配列

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

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

D — クエリ データに対する最近傍の距離

数値ベクトルの cell 配列

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

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

ヒント

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

代替機能

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

拡張機能

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意および制限

• 次の表は、rangesearch の引数に関する注意です。

  引数	注意と制限
  Mdl	コード生成で Mdl を使用する方法は 2 つあります。例については、最近傍探索モデルのコード生成を参照してください。 saveCompactModel、loadCompactModel および codegen を使用して、関数 rangesearch のコードを生成します。saveCompactModel を使用して、学習済みモデルを保存します。loadCompactModel を使用して保存済みモデルを読み込み関数 rangesearch を呼び出す、エントリポイント関数を定義します。次に、codegen を使用して、エントリポイント関数のコードを生成します。 codegen の -args の値に coder.Constant(Mdl) を含めます。
  'Distance'	カスタム距離関数にすることはできません。 コンパイル時の定数でなければなりません。この値は、生成されたコード内では変更できません。
  名前と値のペアの引数	名前と値のペアの引数に含まれる名前はコンパイル時の定数でなければなりません。 たとえば、生成されたコードでミンコフスキー距離についてユーザー定義の指数を使用可能にするには、{coder.Constant('Distance'),coder.Constant('Minkowski'),coder.Constant('P'),0} を codegen の -args の値に含めます。
  Idx	数値の精度のため、生成されたコードにおける同順位の距離の並べ替え順序は MATLAB® における順序と異なる可能性があります。

• コード生成の場合、rangesearch は (既定では) parfor を使用して、サポートされる共有メモリ マルチコア プラットフォームで並列実行されるループを作成します。コンパイラが Open Multiprocessing (OpenMP) アプリケーション インターフェイスをサポートしない場合、または OpenMP ライブラリを無効にした場合、MATLAB Coder™ は parfor ループを for ループとして扱います。サポートされるコンパイラについては、サポートされるコンパイラを参照してください。OpenMP ライブラリを無効にするには、codegen 構成オブジェクトの EnableOpenMP プロパティを false に指定します。詳細については、coder.CodeConfig を参照してください。

詳細については、コード生成の紹介と最近傍探索モデルのコード生成を参照してください。

参考

ExhaustiveSearcher | KDTreeSearcher | createns | knnsearch | rangesearch

トピック

• k 最近傍点検索および半径検索
• 距離計量

R2011b で導入