2017.05.10

                    HMMモデリングツールの使い方
                  ￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
1. ツール概要
￣￣￣￣￣￣￣
  本ツールは、時系列データからHMM(隠れマルコフモデル)によるモデル化と、隠れ状態
  の推定を行うことができます。


2. インストール
￣￣￣￣￣￣￣￣
2.1. 動作環境
￣￣￣￣￣￣￣
  - OS：CentOS 7
  - Pythonバージョン：2.7.12（動作確認済）
  - Pythonモジュール：Anacondaでインストールされるモジュール＋hmmlearn＋
                      timeout_decorator

2.2. モジュール構成
￣￣￣￣￣￣￣￣￣￣
  - README.txt：本ドキュメント
  - hmm.utils.py：内部モジュール（HMM用の関数を定義）
  - optimization.py：内部モジュール（最適化の関数を定義）
  - run_hmm_modeling.py：モデル作成用モジュール
  - run_hmm_predict.py：モデル実行用モジュール

2.3. インストール方法
￣￣￣￣￣￣￣￣￣￣￣
  上記モジュールを同一のディレクトリ配下に配置します。


3. 使用方法
￣￣￣￣￣￣
3.1. HMMモデル作成
￣￣￣￣￣￣￣￣￣
  インストールディレクトリに移動して、以下のコマンドを実行します。

    # python run_hmm_modeing.py <in_path> <tgt_col> <out_path> <state_num>

　  in_path：入力ファイルの絶対パスを指定
    tgt_col：分析対象のカラム名を指定
    out_path：出力ファイルの絶対パスを指定
    state_num：状態数（2以上の整数）を指定

  インストールディレクトリに移動せずに、以下の様に、コマンドのパスを指定して、
  実行することもできます。

    # python /tmp/tooldir/run_hmm_modeing.py <in_path> <tgt_col> <out_path> <state_num>

3.2. HMMモデルで予測を実行
￣￣￣￣￣￣￣￣￣￣￣￣￣
  インストールディレクトリに移動して、以下のコマンドを実行します。

    # python run_hmm_predict.py <in_path> <tgt_col> <out_path> <dump_path>

　  in_path：入力ファイルの絶対パスを指定
    tgt_col：分析対象のカラム名を指定
    out_path：出力ファイルの絶対パスを指定
    dump_path：作成済のモデルオブジェクトファイルの絶対パスを指定

  インストールディレクトリに移動せずに、以下の様に、コマンドのパスを指定して、
  実行することもできます。

    # python /tmp/tooldir/run_hmm_predict.py <in_path> <tgt_col> <out_path> <dump_path>

4. コマンドI/F仕様(run_hmm_modeing.py)
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
4.1. 入力ファイルの条件
￣￣￣￣￣￣￣￣￣￣￣￣
  - ファイルの形式はCSVであること
  - 1レコードが1時点を表す、時系列データを想定
  - カラム名は必須、インデックス有無は問わない
  - 対象カラムのカラム名は、半角英字であること
    （全角文字も動作するが、文字コードや環境依存の問題を考慮し、制限している）
  - 対象カラムのデータは、数値データであること
  - 対象カラムのデータ欠損値は、空値であること
    （実際は、""やNAなど、python(pandas)が欠損値とみなすものであれば動作可能）
  - 改行コードはLFであること

4.2. 出力ファイルの形式
￣￣￣￣￣￣￣￣￣￣￣￣
  - HMMのモデルオブジェクトをpickle化したファイル
  - ファイル名を指定する際の拡張子は任意
    （参考）「.dump」や「.pkl」が使われることが多い

4.3. コマンド引数
￣￣￣￣￣￣￣￣￣
  3. 使用方法を参照

4.4. 復帰値
￣￣￣￣￣￣
  正常終了：0
  異常終了：0以外

4.5. ログの管理
￣￣￣￣￣￣￣￣
  コマンド側ではログファイルは作成しない

4.6. メッセージの出力先
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
  標準出力または、標準エラー出力に出力する


5. コマンドI/F仕様(run_hmm_predict.py)
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
5.1. 入力ファイルの条件
￣￣￣￣￣￣￣￣￣￣￣￣
  - ファイルの形式はCSVであること
  - 1レコードが1時点を表す、時系列データを想定
  - カラム名は必須、インデックス有無は問わない
  - 対象カラムのカラム名は、半角英字であること
    （全角文字も動作するが、文字コードや環境依存の問題を考慮し、制限している）
  - 対象カラムのデータは、数値データであること
  - 対象カラムのデータ欠損値は、空値であること。
    （実際は、""やNAなど、python(pandas)が欠損値とみなすものであれば動作可能）
  - 改行コードはLFであること

5.2. 出力ファイルの形式
￣￣￣￣￣￣￣￣￣￣￣￣
  - カラム名とデータ部分のn行1列のCSV形式で出力
  - インデックスは無し
  - カラム名は、「分析対象カラム名」+「_state」
  - 行数は、入力データと同じ
  - データ部分には、入力データの各行に対応するHMMの状態番号(int)が入る
  - 入力データに空値があった場合、対応する行の値が空値となる
    その際、状態番号の数値は、float型で出力される（pythonの仕様）
    ・欠損が無い場合
     インプット     アウトプット
     whp            whp_state
      10                    0
     100        →          1
     120                    2
     100                    1
     120                    2
    ・欠損がある場合
     インプット     アウトプット
     whp            whp_state
      10                  0.0
     100        →        1.0
      ""                    ""
     120                  2.0
     100                  1.0
     120                  2.0
  - 改行コードはLFで出力する

5.3. コマンド引数
￣￣￣￣￣￣￣￣￣
  3. 使用方法を参照

5.4. 復帰値
￣￣￣￣￣￣
  正常終了：0
  異常終了：0以外

5.5. ログの出力先
￣￣￣￣￣￣￣￣￣
  異常終了した場合のみ、以下のファイルを出力する
  - /var/log/hmm_tools_<日時>_<PID>.log
  
5.6. メッセージの出力先
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
  標準出力または、標準エラー出力に出力する

                                                                      －以上－