uniquetol

許容誤差内の一意の値

構文

C = uniquetol(A,tol)

C = uniquetol(A)

C = uniquetol(A,tol,occurrence)

[C,IA,IC] = uniquetol(___)

[___] = uniquetol(___,Name,Value)

説明

C = uniquetol(A,tol) は、A で許容誤差 tol の範囲内にある一意の要素を返します。u と v の 2 つの値は、次が満たされる場合に許容誤差内にあります。

abs(u-v) <= tol*max(abs(A(:)))

つまり、uniquetol はデータの大きさに基づいて tol 入力をスケーリングします。

uniquetol は unique と似ています。unique は厳密な比較を実行しますが、uniquetol は許容誤差を使用して比較を行います。

C = uniquetol(A) は既定の許容誤差として、単精度の入力に対しては 1e-6 を、倍精度の入力に対しては 1e-12 を使用します。

C = uniquetol(A,tol,occurrence) は、occurrence が 'highest' である場合、複数の値が互いに許容誤差内にあると、最大値が一意であるとして選択されることを指定します。occurrence の既定値は 'lowest' であり、最小値を一意であるとして選択します。

[C,IA,IC] = uniquetol(___) は、インデックス ベクトル IA および IC を返します。ここで、C = A(IA) かつ A~C(IC) (または A が行列の場合は A(:)~C(IC)) であり、~ は値が互いに許容誤差内にあることを示します。前述の構文の入力引数のいずれかを使用できます。

[___] = uniquetol(___,Name,Value) は、前述の構文にある任意の入力引数または出力引数を組み合わせて、1 つ以上の名前と値のペアの引数で指定される追加のオプションを使用します。たとえば、uniquetol(A,'ByRows',true) は A 内で一意の行を判別します。

例

数値誤差がある場合の一意の要素

ベクトル x を作成します。x の変換と復元を実行して、2 番目のベクトル y を取得します。この変換により y で丸め誤差が生じます。

x = (1:6)'*pi;
y = 10.^log10(x);

この誤差を求め、x と y が同一でないことを検証します。

x-y

ans = 6×1
10-14 ×

    0.0444
         0
         0
         0
         0
   -0.3553

unique を使用して、連結ベクトル [x;y] 内の一意の要素を検出します。関数 unique は厳密な比較を実行し、x の一部の値が y の値と厳密には等しくないと判定します。これらは、x-y の差が非ゼロである、同じ要素です。したがって、c には重複しているように "見える" 値が含まれています。

c = unique([x;y])

c = 8×1

    3.1416
    3.1416
    6.2832
    9.4248
   12.5664
   15.7080
   18.8496
   18.8496

uniquetol を使用して、わずかな誤差が許容される比較を実行します。uniquetol は許容誤差内にある要素を等価として扱います。

C = uniquetol([x;y])

C = 6×1

    3.1416
    6.2832
    9.4248
   12.5664
   15.7080
   18.8496

一意の行の特定

既定では、uniquetol は許容誤差内にある一意の "要素" を検出しますが、行列で許容誤差内にある "行" を検出することもできます。

数値行列 A を作成します。A の変換と復元を実行して、2 番目の行列 B を取得します。この変換により B に丸め誤差が生じます。

A = [0.05 0.11 0.18; 0.18 0.21 0.29; 0.34 0.36 0.41; 0.46 0.52 0.76];
B = log10(10.^A);

unique を使用して、A および B 内で一意の行を検出します。関数 unique は厳密な比較を実行し、行の相違がたとえごくわずかであっても、連結行列 [A;B] 内のすべての行が一意であると判定します。

unique([A;B],'rows')

ans = 8×3

    0.0500    0.1100    0.1800
    0.0500    0.1100    0.1800
    0.1800    0.2100    0.2900
    0.1800    0.2100    0.2900
    0.3400    0.3600    0.4100
    0.3400    0.3600    0.4100
    0.4600    0.5200    0.7600
    0.4600    0.5200    0.7600

uniquetol を使用して一意の行を検出します。uniquetol は、許容誤差内にある行を等価として扱います。

uniquetol([A;B],'ByRows',true)

ans = 4×3

    0.0500    0.1100    0.1800
    0.1800    0.2100    0.2900
    0.3400    0.3600    0.4100
    0.4600    0.5200    0.7600

厳密な比較のためのベクトルの準備

ベクトル x を作成します。x の変換と復元を実行して、2 番目のベクトル y を取得します。この変換により、y の一部の要素に丸め誤差が生じます。

x = (1:5)'*pi;
y = 10.^log10(x);

x と y を単一のベクトル A に組み合わせます。uniquetol を使用して A を再作成します。その際、許容誤差内にある値を等価として扱います。

A = [x;y]

A = 10×1

    3.1416
    6.2832
    9.4248
   12.5664
   15.7080
    3.1416
    6.2832
    9.4248
   12.5664
   15.7080

[C,IA,IC] = uniquetol(A);
newA = C(IC)

newA = 10×1

    3.1416
    6.2832
    9.4248
   12.5664
   15.7080
    3.1416
    6.2832
    9.4248
   12.5664
   15.7080

この後のコードでは、newA と == を同時に使用したり、完全な等価性を評価する isequal や unique などの関数を使用したりできます。

D1 = unique(A)

D1 = 6×1

    3.1416
    3.1416
    6.2832
    9.4248
   12.5664
   15.7080

D2 = unique(newA)

D2 = 5×1

    3.1416
    6.2832
    9.4248
   12.5664
   15.7080

一意の値の選択を制御する

occurrence オプションを使用して、uniquetol がどの要素を一意であるとして選択するか制御します。

ベクトルを作成し、どの要素が 1e-1 の許容誤差内で一意であるか検索します。

a = [1 1.1 1.11 1.12 1.13 2];
c = uniquetol(a,1e-1)

c = 1×2

     1     2

A にある最初の 5 つの要素はすべて 1e-1 の許容誤差に関して類似した値であるため、その中の最小値のみが一意であるとして選択されます。これは uniquetol が a にある最小値から開始して、ベクトルの最後にある 2 に到達するまで、許容誤差の範囲外となる要素を新たに検出しないためです。

'highest' オプションを使用して、uniquetol が a にある最大値から開始するように指定します。すると、uniquetol が最大値から小さい方へ動作するため、1.13 要素が一意であるとして選択されます。

d = uniquetol(a,1e-1,'highest')

d = 1×2

    1.1300    2.0000

大きな許容誤差を使用したデータのサブセット化

2 次元サンプル点の点群を作成し、点 $$(\frac{1}{2},\frac{1}{2})$$ を中心とする半径 0.5 の円内に制限します。

x = rand(10000,2); 
insideCircle = sqrt((x(:,1)-.5).^2+(x(:,2)-.5).^2)<0.5;
y = x(insideCircle,:);

元のデータセットの各点が、特定の点の許容誤差内になるよう、点の数を絞り込みます。

tol = 0.05;
C = uniquetol(y,tol,'ByRows',true);

絞り込んだ後の点を、元のデータ セットの上に赤でプロットします。赤い点はすべて元のデータ セットのメンバーです。すべての赤い点の間には少なくとも tol の距離があります。

plot(y(:,1),y(:,2),'.')
hold on
axis equal
plot(C(:,1), C(:,2), '.r', 'MarkerSize', 10)

ベクトルの平均類似値

乱数のベクトルを作成し、許容誤差を使用して一意の要素を判定します。OutputAllIndices を true に指定して、一意の値の許容誤差内にある要素のインデックスをすべて返します。

A = rand(100,1);
[C,IA] = uniquetol(A,1e-2,'OutputAllIndices',true);

値 C(2) の許容誤差内にある要素の平均値を求めます。

C(2)

ans = 0.0318

allA = A(IA{2})

allA = 3×1

    0.0357
    0.0318
    0.0344

aveA = mean(allA)

aveA = 0.0340

絶対許容誤差の指定

既定の設定では、uniquetol は abs(u-v) <= tol*DS の形式の許容誤差テストを使用します。ここで、DS は入力データの大きさに基づいて自動的に "スケーリング" を行います。DS に異なる値を指定して、DataScale オプションと共に使用できます。ただし、(DS がスカラーである場合の) 絶対許容誤差は、入力データの大きさに基づいてスケーリングされません。

まず、距離が eps だけ離れている 2 つの小さい値を比較します。tol と DS を指定して、abs(u-v) <= 10^-6 という許容誤差内の式を作成します。

x = 0.1;
uniquetol([x, exp(log(x))], 10^-6, 'DataScale', 1)

ans = 0.1000

次に、値を大きくします。exp(log(x)) の計算の丸め誤差は値の大きさ、つまり eps(x) に比例します。2 つの大きい値間の距離が eps であっても、eps(x) はこれを大きく上回る値になります。したがって、10^-6 は許容誤差として適切でなくなります。

x = 10^10;
uniquetol([x, exp(log(x))], 10^-6, 'DataScale', 1)

ans = 1×2
1010 ×

    1.0000    1.0000

この問題を修正するには、DS の既定値 (スケーリングされる) を使用します。

format long
Y = [0.1 10^10];
uniquetol([Y, exp(log(Y))])

ans = 1×2
1010 ×

   0.000000000010000   1.000000000000000

列単位の DataScale の指定

2 次元の乱数点のセットを作成します。次に uniquetol を使用して、これらの点を類似した (許容誤差内の) x 座標をもつ縦の複数の帯域にグループ化します。uniquetol には次のオプションを指定します。

• 点の座標は A の行に含まれるため、ByRows を true に指定します。

• OutputAllIndices を true に指定して、互いに許容誤差内にある x 座標をもつすべての点のインデックスを返すようにします。

• x 座標に絶対許容誤差を使用して、y 座標は無視するために、DataScale は [1 Inf] に指定します。

A = rand(1000,2);
DS = [1 Inf];
[C,IA] = uniquetol(A, 0.1, 'ByRows', true, ...
    'OutputAllIndices', true, 'DataScale', DS);

各帯域の点と平均値をプロットします。

hold on
for k = 1:length(IA)
    plot(A(IA{k},1), A(IA{k},2), '.')
    meanAi = mean(A(IA{k},:));
    plot(meanAi(1), meanAi(2), 'xr')
end

入力引数

A — クエリ配列

スカラー | ベクトル | 行列 | 多次元配列

クエリ配列。スカラー、ベクトル、行列または多次元配列として指定します。A は、非スパースでなければなりません。

データ型: single | double

tol — 比較許容誤差

正の実数のスカラー

比較許容誤差。正の実数のスカラーとして指定します。uniquetol は、入力配列 A の最大絶対値を使用して tol の入力をスケーリングします。続いて、uniquetol はスケールされた結果の比較許容誤差を使用して、A のどの要素が一意であるかを判別します。A の 2 つの要素が互いに許容誤差内にある場合、uniquetol はこれらの要素を等価とみなします。

u と v の 2 つの値は、abs(u-v) <= tol*max(abs(A)) である場合に許容誤差内にあります。

絶対許容誤差を指定するには、tol および名前と値のペア 'DataScale' の両方を指定します。

例: tol = 0.05

例: tol = 1e-8

例: tol = eps

データ型: single | double

occurrence — 一意の値の出現

'lowest' (既定値) | 'highest'

一意の値の出現。次の表のオプションのいずれかとして指定します。occurrence の値は、uniquetol がどの要素を一意であるとして選択するか決定します。

オプション	説明
'lowest'	uniquetol は A の最小値から開始し、A の中から C にある他のいかなる値とも許容誤差の範囲外となる次の最小値を繰り返し検索します。この結果、複数の入力値が互いに許容誤差内にあると、最小値が一意であるとして選択されます。
'highest'	uniquetol は A の最大値から開始し、A の中から C にある他のいかなる値とも許容誤差の範囲外となる次の最大値を繰り返し検索します。この結果、複数の入力値が互いに許容誤差内にあると、最大値が一意であるとして選択されます。

例: C = uniquetol(A,tol,'highest')

例: C = uniquetol([1 2 3],2,'highest') は、uniquetol が入力の最大値から開始し、ほかのすべての値が許容誤差内にあるため、3 を返します。

データ型: char | string

名前と値の引数

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

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

例: C = uniquetol(A,'ByRows',true)

OutputAllIndices — 出力インデックス タイプ

false (既定値) | true | 0 | 1

出力インデックス タイプ。'OutputAllIndices' と、false (既定)、true、0 または 1 のいずれかで構成されるコンマ区切りのペアとして指定します。uniquetol は、数値の 0 を false、1 を true と解釈します。

OutputAllIndices が true である場合、関数 uniquetol は 2 番目の出力 IA を cell 配列として返します。cell 配列には、C の値から許容誤差内にある A の "すべての" 要素のインデックスが含まれます。つまり、IA の各セルが C の値に対応し、各セル内の値は A での位置に対応します。

例: [C,IA] = uniquetol(A,tol,'OutputAllIndices',true)

ByRows — 行比較の切り替え

false (既定値) | true | 0 | 1

行比較の切り替え。'ByRows' と、false (既定)、true、0 または 1 のいずれかで構成されるコンマ区切りのペアとして指定します。uniquetol は数値の 0 を false、数値の 1 を true と解釈します。このオプションを使用して、許容誤差内で一意である行を A 内で検索します。

ByRows が true である場合、次のようになります。

• A は 2 次元配列でなければなりません。

• uniquetol は、A の行を各列ごとに個別に比較します。2 つの行が互いに許容誤差内にあるとみなされるには、各列が許容誤差内になければなりません。

• A の各行が、C のいずれかの行の許容誤差内にあります。しかし、C 内には、互いに許容誤差内にある行は 2 つ存在しません。

u と v の 2 つの行は、all(abs(u-v) <= tol*max(abs(A),[],1)) の場合に許容誤差内にあります。

例: C = uniquetol(A,tol,'ByRows',true)

DataScale — データのスケール

スカラー | ベクトル

データのスケール。'DataScale' と、スカラーまたはベクトルで構成されるコンマ区切りのペアとして指定します。許容誤差のテストが abs(u-v) <= tol*DS になるよう変更するには、DataScale を数値スカラー DS として指定します。

ByRows オプションと共に使用する場合、DataScale の値をベクトルにすることもできます。この場合、ベクトルの各要素は A で対応する列の DS を指定します。DataScale ベクトルの値が Inf である場合、uniquetol は A の対応する列を無視します。

例: C = uniquetol(A,'DataScale',1)

例: [C,IA,IC] = uniquetol(A,'ByRows',true,'DataScale',[eps(1) eps(10) eps(100)])

データ型: single | double

PreserveRange — 保持範囲の切り替え

false (既定値) | true | 0 | 1

保持範囲の切り替え。'PreserveRange' と、false (既定)、true、0 または 1 のいずれかで構成されるコンマ区切りのペアとして指定します。uniquetol は数値の 0 を false、数値の 1 を true と解釈します。このオプションを使用して、出力 C 内の最小値および最大値が A 内のその値と同じになるように指定します。

A の最小値および最大値が互いに許容誤差 tol 内にある場合、uniquetol はこの値の 1 つのみを返します。

例: C = uniquetol(A,tol,'PreserveRange',true)

出力引数

C — A 内の一意の要素

ベクトル | 行列

A 内の (許容誤差内で) 一意の要素。ベクトルまたは行列として返されます。A が行ベクトルの場合、C も行ベクトルになります。それ以外の場合は、C は列ベクトルになります。C の要素は昇順に並んでいます。A の各要素は C のいずれかの要素の許容誤差内にありますが、C 内で互いに許容誤差内にある要素は 2 つありません。

ByRows オプションが true の場合、C は A の一意の行を含む行列となります。この場合、C の行は、最初の列を基準とする昇順に並んでいます。A の各行は C のいずれかの要素の許容誤差内にありますが、C 内で互いに許容誤差内にある行は 2 つありません。

IA — A のインデックス

列ベクトル | cell 配列

A のインデックス。反復される要素の最初の出現に対するインデックスの列ベクトル、あるいは cell 配列として返されます。IA は、次の例外を除いて通常は C = A(IA) を満たします。

• ByRows オプションが true の場合、C = A(IA,:) です。

• OutputAllIndices オプションが true の場合、IA は cell 配列となり、C(i)~A(IA{i}) になります。ここで ~ は、値が互いに許容誤差内にあることを示します。

IC — C のインデックス

列ベクトル

C のインデックス。インデックスの列ベクトルとして返されます。IC は次のプロパティを満たします。ここで ~ は、値が互いに許容誤差内にあることを示します。

• A がベクトルの場合、A~C(IC) です。

• A が行列の場合、A(:)~C(IC) です。

• ByRows オプションが true の場合、A~C(IC,:) です。

アルゴリズム

uniquetol は入力を辞書順に並べ替えたうえで、最も低い値または最も高い値から開始して許容誤差内にある一意な値を検出します。そのため、入力の並べ替え順序を変更すると、出力が変化する可能性があります。たとえば、uniquetol(-A) で返される結果が -uniquetol(A) の結果とは異なる場合があります。

"C 内には互いに許容誤差内にある要素が 2 つあってはならない" という条件を満たす有効な出力 C が複数存在する場合もあります。関数 uniquetol は、occurrence の値が 'highest' または 'lowest' であるか、および PreserveRange オプションが指定されているかに応じて、複数の有効な出力を返すことができます。

拡張機能

スレッドベースの環境

MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

この関数はスレッドベースの環境を完全にサポートしています。詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

GPU 配列

Parallel Computing Toolbox™ を使用してグラフィックス処理装置 (GPU) 上で実行することにより、コードを高速化します。

使用上の注意事項および制限事項:

• 一意の値の出現に対して occurrence 引数はサポートされていません。

• 'ByRows'、'OutputAllIndices' および 'PreserveRange' のオプションはサポートされません。

• 64 ビット整数はサポートされません。

詳細については、GPU での MATLAB 関数の実行 (Parallel Computing Toolbox)を参照してください。

バージョン履歴

R2015a で導入

R2021b: 要素の選択を制御するオプションとデータの範囲を保持するオプション

occurrence 引数は、入力データの最も大きい要素と最も小さい要素のどちらからアルゴリズムを開始するかを制御します。名前と値の引数 'PreserveRange' は、出力データの範囲を入力データと同じにするかどうかを指定します。

参考

ismembertol | unique | ismember | eps

トピック

• 許容誤差を使用した類似するデータ点の平均化