% MLE   最尤推定
%
%   PHAT = MLE(DATA) は、ベクトル DATA 内のサンプルデータを使って計算
%   された正規分布のパラメータに対する最尤推定 (MLE) を出力します。
%  
%   [PHAT, PCI] = MLE(DATA) は、MLE とパラメータの 95% の信頼区間を出力します。
%
%   [...] = MLE(DATA,'distribution',DIST) は、DIST で指定された分布に
%   対するパラメータ推定を計算します。DISTは MLE をサポートする分布の 
%   1 つの名前を含む文字列です。
%
%   [...] = MLE(DATA, ..., 'NAME1',VALUE1,'NAME2',VALUE2,...) は、以下の
%   リストから選択されるオプション引数の名前/値の組み合わせを指定します。
%
%        名前           値
%      'censoring'    DATA の対応する要素が右側打ち切りの場合に 1 で、
%                     対応する要素が正しい観測の場合に 0 を含む DATA と
%                     同じサイズの boolean のベクトルです。
%                     デフォルトは、すべて正しく観測された観測値です。
%                     打ち切りはすべての分布に対してサポートされていません。
%      'frequency'    DATA の対応する要素に対する非負の整数の頻度を含む
%                     DATA と同じサイズのベクトルです。デフォルトは、
%                     DATA の1つの要素に対して 1 つの観測です。
%      'alpha'        PCI に対する 100*(1-alpha)% の信頼区間を指定する
%                     0 か 1 の間の値です。デフォルトは、95% の信頼区間に
%                     対して alpha=0.05 です。
%      'ntrials'      DATA の対応する要素に対する試行の総数を含む DATA と
%                     同じサイズのスカラ、またはベクトルです。
%                     二項分布にのみ適用されます。
%      'options'      適合アルゴリズムに対する数値オプションを含む 
%                     STATSET を呼び出すことで作成される構造体です。
%                     すべての分布に適用可能ではありません。
%
%   MLE は、分布関数を使って定義されたカスタムの分布に適合することも
%   可能です。つぎの 3 つの方法のいずれかを使います:
%
%   [...] = MLE(DATA,'pdf',PDF,'cdf',CDF,'start',START,...) は、確率密度と
%   累積分布関数 PDF と CDF で定義された分布のパラメータに対する MLE を
%   出力します。PDF と CDF は、@ を使って作成された関数ハンドルです。
%   これらは、データと 1 つ以上の個々の分布パラメータの入力を受け入れ、
%   確率密度の値と累積分布の値を別々に返します。'censoring' の名前/値の
%   組が存在しない場合、'cdf' の名前/値の組み合わせを省略できます。MLE は、
%  分布の対数尤度を数値的に最大にすることで推定を計算し、START は、
%  パラメータに対する初期値を含むベクトルになります。
% 
%   [...] = MLE(DATA,'logpdf',LOGPDF,'logsf',LOGSF,'start',START,...) は、
%   対数確率密度と対数生存関数 LOGPDF と LOGSF で定義された分布のパラメータ
%   に対する MLE を出力します。LOGPDF と LOGSF は、@ を使って作成された
%   関数ハンドルです。これらは、データと 1 つ以上の個々の分布パラメータの
%   入力を受け入れ、対数の分布密度の値と対数の生存関数の値を別々に返します。
%   この形式は、PDF と CDF 関数を使うことで、時々開始点の選択のために
%   よりロバストになります。。'censoring' の名前/値の組が存在しない場合、
%   'logsf' の名前/値の組み合わせを省略できます。START は、分布のパラメータ
%   に対する初期値を含むベクトルになります。
%
%   [...] = MLE(DATA,'nloglf',NLOGLF,'start',START,...) は、NLOGLF で
%   与えられた分布の負の対数尤度のパラメータに対する MLE を出力します。
%   NLOGLF は、4 つの入力引数を受け入れる @ を使って作成された関数ハンドル
%   です。
%      PARAMS - 分布パラメータ値のベクトル
%      DATA   - データのベクトル
%      CENS   - 打ち切りの値のブーリアンベクトル
%      FREQ   - 整数のデータの頻度のベクトル
%   NLOGLF は、'censoring' または 'frequency' の名前/値の組み合わせ 
%   (上記を参照) を指定しなくても、4 つの引数すべてを与えなければなり
%   ません。しかし、NLOGLF は、CENS と FREQ の引数を無視することはできます。
%   NLOGLF は、スカラの負の対数尤度値と、さらに、負の対数尤度の勾配ベクトルを
%   出力します ('GradObj' の STATSET は以下を参照してください)。START は、
%   分布のパラメータに対する初期値を含むベクトルです。
%
%   PDF, CDF, LOGPDF, LOGSF, または NLOGLF は、最初の要素が上記で定義された
%   関数ハンドルで、残りの要素が関数への追加の引数となるセル配列にもなります。
%   MLE は関数呼び出しの引数リストの最後にこれらの引数を置きます。
%
%   つぎの追加の引数 名前/値 の組み合わせは、'pdf' と 'cdf'、'logpdf' と 
%   'logcdf'、あるいは 'nloglf' が与えられた場合にのみ有効です。
%
%      'lowerbound'   分布パラメータに対する下限を含む START と同じサイズの
%                     ベクトルです。デフォルトは -Inf です。
%      'upperbound'   分布パラメータに対する上限を含む START と同じサイズの
%                     ベクトルです。デフォルトは Inf です。
%      'optimfun'     尤度を最大にするための最適化関数名の 'fminsearch' 
%                     あるいは 'fmincon' のいずれかの文字列です。
%                     デフォルトは、'fminsearch' です。Optimization Toolbox が
%                     利用可能な場合、'fmincon' のみ指定することができます。
%
%   カスタムの分布に適合する場合、最尤最適化の詳細を制御するために 'options' 
%   パラメータを使います。パラメータ名とデフォルト値については、
%   STATSET('mlecustom') を参照してください。MLE は、つぎのように、
%   適合するカスタムの分布に対して以下の STATSET パラメータを解釈します:
%
%      'GradObj'      2 番目の出力として負の対数尤度の勾配ベクトルを出力
%                     するために、'nloglf' の 名前/値 の組み合わせで
%                     与えられた関数と予測される FMINCON かどうかを示す
%                     'on' か 'off' の文字列です。デフォルトは 'off' です。
%                      FMINSEARCH が使われるときは無視されます。
%      'DerivStep'    相対微分は、FMINCON を使う場合の有限差分による
%                     導関数近似で使われ、'GradObj' は 'off' になります。
%                     スカラか、START と同じサイズです。デフォルトは、
%                     EPS^(1/3) です。FMINSEARCH を使う場合は無視されます。
%      'FunValCheck'  MLE は妥当性に対するカスタムな分布関数によって
%                     出力された値をチェックするかどうかを示す 'on' か 
%                     'off' の文字列です。デフォルトは 'on' です。
%                     開始点の良くない選択は、適切なエラーチェックなしで
%                     記述されている場合、時々これらの関数は、NaN や
%                     無限値、あるいは、範囲外の値を返すことになります。
%       'TolBnd'      FMINCON を使う場合の上限と下限に対するオフセットです。
%                     MLE は、厳密な不等式 (すなわち、開境界) として
%                     上限と下限を扱います。FMINCON は、これは TolBnd で
%                     指定した上限と下限から挿入される閉じた境界を作る
%                     ことによる近似です。デフォルトは、1e-6 です。
%
%   参考 BETAFIT, BINOFIT, EXPFIT, EVFIT, GAMFIT, LOGNFIT, NORMFIT,
%        NBINFIT, POISSFIT, RAYLFIT, UNIFIT, WBLFIT, MLECOV, STATSET.


%   Copyright 1993-2007 The MathWorks, Inc.