% KMEANS   K平均クラスタリング
%
% IDX = KMEANS(X, K) は、K 個のクラスタへ N×P データ行列 X の点を分割
% します。この区分は、すべてのクラスタにわたってクラスタの中心点への
% 距離のクラスタ内の和を最小化します。X の行は、点に対応し、列は変数に
% 対応します。KMEANS は、各点のクラスタのインデックスを含む、N×1 の
% ベクトル IDX を出力します。デフォルトでは、KMEANS は、Euclidean 
% 距離の二乗を用います。
%
% KMEANS は、欠損値を NaN として扱い、NaN を含む X のいずれの行も削除します。
%
% [IDX, C] = KMEANS(X, K) は、K×P 行列 C に K 個のクラスタ中心の位置
% を出力します。
%
% [IDX, C, SUMD] = KMEANS(X, K) は、1×K ベクトル sumD に中心点への距離
% のクラスタ内の和を出力します。
%
% [IDX, C, SUMD, D] = KMEANS(X, K) は、N×K 行列 D に各点からすべての
% 中心への距離を出力します。
%
% [ ... ] = KMEANS(..., 'PARAM1',val1, 'PARAM2',val2, ...) は、KMEANS で
% 使用される反復アルゴリズムをコントロールするために、オプションのパラ
% メータの名前と値の組を指定することが可能です。パラメータは以下の通り
% です。:
%
% 'Distance' - KMEANS が最小にすべきP次元空間における距離の測定法。
%              以下から選択します。:
%          {'sqEuclidean'} - Euclidean 距離の二乗
%           'cityblock'    - 絶対距離(別名 L1)の和
%           'cosine'       - 1から(ベクトルとして扱われた)点の間の角度
%                            のコサインを引いた値
%           'correlation'  - 1から(値の系列として扱われた)点の間の標本
%                            相関を引いた値
%           'Hamming'      - 異なるビットのパーセンテージ
%                            (2値のデータに対してのみ適応)
%
% 'Start' - "seeds"としても知られる、クラスタの初期の中心位置を選択する
%           ために使われる方法。以下から選択します。:
%               {'sample'} - ランダムに X から K の観測を選択
%                'uniform' - X の範囲から一様にランダムな K 点を選択。
%                            Hamming 距離に対しては指定できません。
%                'cluster' - X の 10% をランダムに抽出し予備のクラスタ
%                            リングを実行します。この予備クラスタリング
%                            の初期値は 'sample' を用いて計算されます。
%                matrix    - 開始位置の K×P 行列。この場合、K に対して
%                            [] を渡し、KMEANS にこの行列の最初の次元
%                            から K を推測させることができます。3つめ
%                            の次元から 'Replicates' に対する値を指し
%                            示すように、3次元配列を与えることもでき
%                            ます。
%
% 'Replicates' - それぞれ新しい初期の中心の設定を使うクラスタリングの
%                繰り返し回数 [ 正の整数 | {1}]
% 'Maxiter' - 繰り返し最大数 [ 正の整数 | {100}]
%
% 'EmptyAction' - あるクラスタがそれを構成する観測すべてを失う場合に
%                 取るアクション。以下から選択します。:
%             {'error'}    - 誤差として空のクラスタを取り扱う
%              'drop'      - 空の場合に任意のクラスタを消去し、C と D
%                            に対応する値に NaN を設定
%              'singleton' - 中心からもっとも遠い一つの観測から新しい
%                            クラスタを作成
%
% 'Display' - 表示レベル [ 'off' | {'notify'} | 'final' | 'iter' ]
%
% 例題:
%
%     X = [randn(20,2)+ones(20,2); randn(20,2)-ones(20,2)];
%     [cidx, ctrs] = kmeans(X, 2, 'dist','city', 'rep',5, 'disp','final');
%     plot(X(cidx==1,1),X(cidx==1,2),'r.', ...
%          X(cidx==2,1),X(cidx==2,2),'b.', ctrs(:,1),ctrs(:,2),'kx');
%
%   参考 LINKAGE, CLUSTERDATA, SILHOUETTE.


%   Copyright 1993-2004 The MathWorks, Inc.