ドキュメンテーション

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

rangesearch

入力データを使用して指定距離内の近傍をすべて探索

説明

Idx = rangesearch(X,Y,r) は、Y 点の距離 r 内にあるすべての X 点を検索します。XY の行は観測値に、列は変数に対応します。

[Idx,D] = rangesearch(X,Y,r) は、距離が r 以内である Y の点と X の点の間の距離も返します。

[Idx,D] = rangesearch(X,Y,r,Name,Value) では、1 つ以上の名前と値のペアの引数を使用して追加オプションを指定します。たとえば、探索で使用する最近傍探索法や距離計量を指定できます。

すべて折りたたむ

Y 点のユークリッド距離 1.5 内にある X 点を求めます。XY はどちらも、5 次元正規分布変数の標本です。

rng('default') % For reproducibility
X = randn(100,5);
Y = randn(10,5);
[Idx,D] = rangesearch(X,Y,1.5)
Idx = 10x1 cell array
    {1x7  double}
    {1x2  double}
    {1x11 double}
    {1x2  double}
    {1x12 double}
    {1x9  double}
    {[       89]}
    {1x0  double}
    {1x0  double}
    {1x0  double}

D = 10x1 cell array
    {1x7  double}
    {1x2  double}
    {1x11 double}
    {1x2  double}
    {1x12 double}
    {1x9  double}
    {[   1.1739]}
    {1x0  double}
    {1x0  double}
    {1x0  double}

このケースでは、Y の最後の 3 つの点は、X のどの点からも距離が 1.5 より離れています。X(89,:)Y(7,:) から距離が 1.1739 離れており、他の X の点はすべて Y(7,:) からの距離が 1.5 より離れています。X には、Y(5,:) からの距離が 1.5 以内である点が 12 個含まれています。

3 つの異なる多変量正規分布のそれぞれから、5000 個のランダムな点を生成します。無作為に生成した点が 3 つの異なるクラスターを形成する可能性が高くなるように、分布の平均をシフトします。

rng('default')  % For reproducibility
N = 5000;
dist = 10;
X = [mvnrnd([0 0],eye(2),N);
     mvnrnd(dist*[1 1],eye(2),N);
     mvnrnd(dist*[-1 -1],eye(2),N)];

X 内の各点について、その点から半径 dist 以内にある X 内の点を求めます。計算を高速化するため、最近傍のインデックスを並べ替えないように指定します。X 内の最初の点を選択し、その最近傍を求めます。

Idx = rangesearch(X,X,dist,'SortIndices',false);
x = X(1,:);
nearestPoints = X(Idx{1},:);

x の最近傍ではない X 内の値を求めます。これらの点をある色で、x の最近傍を別の色で表示します。黒で塗りつぶした円で点 x にラベルを付けます。

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

年齢および体重が Y 内の患者に対して特定の範囲内にある patients データセット内の患者を求めます。

patients データセットを読み込みます。Age の値の単位は年、Weight の値の単位はポンドです。

load patients
X = [Age Weight];
Y = [20 162; 30 169; 40 168];   % New patients

年齢と体重に関する患者間の距離を決定するカスタム距離関数 distfun を作成します。distfun に従うと、たとえば、年齢が 1 年離れており体重が同じである 2 人の患者は、距離が 1 単位離れています。同様に、年齢が同じであり体重が 5 ポンド離れている 2 人の患者も、距離が 1 単位離れています。

type distfun.m % Display contents of distfun.m file
function D2 = distfun(ZI,ZJ)
ageDifference = abs(ZI(1)-ZJ(:,1));
weightDifference = abs(ZI(2)-ZJ(:,2));
D2 = ageDifference + 0.2*weightDifference;
end

メモ: この例の右上にあるボタンをクリックして例を MATLAB® で開くと、例のフォルダーが開きます。このフォルダーには、関数のファイル distfun.m が含まれています。

Y 内の患者に対する距離が 2 以内である X 内の患者を求めます。

[Idx,D] = rangesearch(X,Y,2,'Distance',@distfun)
Idx = 3x1 cell array
    {1x0 double}
    {1x0 double}
    {[      41]}

D = 3x1 cell array
    {1x0 double}
    {1x0 double}
    {[  1.8000]}

距離が 2 以内である患者が X 内に存在するのは、Y 内の 3 番目の患者だけです。

年齢が 40、体重が 168 である患者に最も近い X 内の患者の AgeWeight の値を表示します。

X(Idx{3},:)
ans = 1×2

    39   164

入力引数

すべて折りたたむ

入力データ。各行が 1 つの n 次元点を表す、mx 行 n 列の数値行列を指定します。n の列数は、Y の列数と等しくなければなりません。

データ型: single | double

クエリ点。各行が 1 つの n 次元点を表す、my 行 n 列の数値行列を指定します。n の列数は、X の列数と等しくなければなりません。

データ型: single | double

各クエリ点に対する探索半径。非負のスカラーを指定します。rangesearch は、Y の各点からの距離が r 以内である X の点 (行) をすべて求めます。距離の意味は、名前と値のペアの引数 'Distance' に依存します。

データ型: single | double

名前と値のペアの引数

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

例: rangesearch(X,Y,1.4,'Distance','seuclidean','Scale',iqr(X)) は、X の四分位数間範囲によってスケーリングされた、標準化されたユークリッド距離を使用して、Y 内の各観測値からの距離が 1.4 以内である X 内の観測値をすべて求めるよう指定します。

最近傍探索法。'NSMethod' と次のいずれかの値から構成されるコンマ区切りのペアとして指定します。

説明
'kdtree'

Kd 木を作成および使用して最近傍を探索します。'kdtree' は、距離計量が次のいずれかである場合のみ有効です。

  • 'chebychev'

  • 'cityblock'

  • 'euclidean'

  • 'minkowski'

'exhaustive'網羅的探索アルゴリズムを使用します。最近傍点を求めるため、X のすべての点から Y の各点までの距離が計算されます。

X の列数が 10 以下であり、X がスパースではなく、距離計量が 'kdtree' で有効な尺度のいずれかである場合、'kdtree' が既定値になります。それ以外の場合、既定値は 'exhaustive' です。

例: 'NSMethod','exhaustive'

rangesearch が使用する距離計量。'Distance' と次の表のいずれかの値から構成されるコンマ区切りのペアとして指定します。

説明
'euclidean'ユークリッド距離。
'seuclidean'標準化されたユークリッド距離。X の行とクエリ点の間の各座標差は、X から計算される標準偏差 nanstd(X) の対応する要素で除算することによりスケーリングされます。他のスケーリングを指定するには、名前と値のペアの引数 'Scale' を使用します。
'mahalanobis'正定共分散行列 C を使用して計算される、マハラノビス距離。C の既定値は X の標本共分散行列であり、nancov(X) によって計算されます。C に別の値を指定するには、'Cov' 名前と値のペアの引数を使用します。
'cityblock'市街地距離。
'minkowski'ミンコフスキー距離。既定の指数は 2 です。別の指数を指定するには、'P' 名前と値のペアの引数を使用します。
'chebychev'チェビシェフ距離 (最大座標差)。
'cosine'1 から、ベクトルとして扱われる観測間の夾角の余弦を引きます。
'correlation'1 から、一連の値として扱われる観測間の標本線形相関係数を引きます。
'hamming'異なる座標の比率を示すハミング距離。
'jaccard'1 から、ジャカード係数 (異なる非ゼロ座標の比率) を引いた値。
'spearman'1 から、観測値間の標本スピアマンの順位相関 (値の系列として扱われる) を引いた値。
@distfun

カスタム距離関数のハンドル。距離関数の形式は次のようになります。

function D2 = distfun(ZI,ZJ)
% calculation of distance
...
ここで、

  • ZI は、X または Y の 1 行が格納されている 1 行 n 列のベクトルです。

  • ZJ は複数行の X または Y を含む m 行 n 列の行列です。

  • D2 は m 行 1 列の距離のベクトルであり、D2(j) は観測値 ZIZJ(j,:) の間の距離です。

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

例: 'Distance','minkowski'

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

例: 'P',4

データ型: single | double

マハラノビス距離計量の共分散行列。'Cov' と正定行列から構成されるコンマ区切りのペアとして指定します。この引数は、'Distance''mahalanobis' である場合のみ有効です。

例: 'Cov',eye(4)

データ型: single | double

標準化されたユークリッド距離計量のスケール パラメーター値。'Scale' と非負のベクトルから構成されるコンマ区切りのペアとして指定します。Scale の長さは X の列数と同じです。X の行とクエリ点の間の各座標差は、Scale の対応する要素でスケーリングされます。この引数は、'Distance''seuclidean' である場合のみ有効です。

例: 'Scale',iqr(X)

データ型: single | double

Kd 木の葉ノードにおけるデータ点の最大数。'BucketSize' と正の整数スカラーから構成されるコンマ区切りのペアとして指定します。この引数は、NSMethod'kdtree' である場合のみ有効です。

例: 'BucketSize',20

データ型: single | double

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

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

例: 'SortIndices',false

データ型: logical

出力引数

すべて折りたたむ

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

Idx は my 行 1 列の cell 配列です。my は Y の行数です。ベクトル Idx{j} には、Y(j,:) に対する距離が r 以下である X 内の点 (行) のインデックスが格納されます。SortIndicestrue である場合、rangesearch はインデックスを距離の昇順で並べ替えます。

クエリ点に対する最近傍点の距離。数値ベクトルの cell 配列として返されます。

D は my 行 1 列の cell 配列です。my は Y の行数です。D{j} には、X(Idx{j},:) 内の点 (行) と Y(j,:) の間の距離の値が格納されます。SortIndicestrue である場合、rangesearch は距離を昇順で並べ替えます。

ヒント

  • rangesearch は、固定された正の実数値 r に対して、Y の各点からの距離が r 以内である X の点をすべて求めます。固定された正の整数 k に対して、Y の各点に最も近い X 内の点を k 個求めるには、knnsearch を使用します。

  • rangesearch は、探索オブジェクトを保存しません。探索オブジェクトを作成するには、createns を使用します。

アルゴリズム

  • kd 木アルゴリズムの概要については、kd 木を使用した K 最近傍点検索を参照してください。

  • 網羅的探索アルゴリズムでは、X 内の各点から Y 内の各点までの距離を求めます。

代替機能

関数 rangesearch の名前と値のペアの引数 'NSMethod' を適切な値 (網羅的探索アルゴリズムの場合は 'exhaustive'、Kd 木アルゴリズムの場合は 'kdtree') に設定した場合、オブジェクト関数 rangesearch を使用して距離探索を実行することにより得られる結果と同じ探索結果になります。関数 rangesearch とは異なり、オブジェクト関数 rangesearch では ExhaustiveSearcher または KDTreeSearcher モデル オブジェクトが必要です。

拡張機能

R2011b で導入