======================
文書分類を実行する
======================

.. Contents:: 目次
    :local:
    :depth: 1

.. highlight:: console



はじめに
=========

| 文書分類とは文書を定められたいくつかのカテゴリに分類する機能です。
| ここでは文書分類学習と文書分類予測を行います。
| 「テキスト分析 with Deep Learning」(TDL)の文書分類機能を用いた分析の例として、小説の一部分からその小説の著者が宮沢賢治か否かを予測します。


実行準備
===========

データを準備する
----------------

| 文書分類を実行するためには各文書が属するべき正しいカテゴリ名を指定した正解ラベルとテキストデータをまとめた学習データであらかじめ学習する必要があります。


| テキストデータをTDLが読み込めるCSV形式に加工します。
| テキストデータの加工に関してはテキストエディタなどを使用して実施することも可能ですが、TDLが提供するデータ整形コマンドを使用することができます。


| ここでは、事前に用意したデータを使用して以降の手順を進めます。


| 1. ユーザがアクセス可能なディレクトリに *tdl-getting_started.zip* を格納します。

| 2. 格納したファイルを解凍します。

::
	
	$ unzip tdl-getting_started.zip
	
| 3. ディレクトリを移動します。以降の操作は本ディレクトリ内で実施します。

::

	$ cd tdl-getting_started

| データは *./examples/sample_data/classification/* にあります。
| 以下にデータ例として予測に用いるデータを示しています。予測に用いるデータには正解ラベルは必須ではありませんが、精度評価のために使用します。

============== ================================ ================================== ==============
index          tag1                             text                               label         
============== ================================ ================================== ==============
0              R3S3_CV_KENJI_GINGA.txt          一　午後の授業。「では...          P
1              R3S3_CV_KENJI_GINGA.txt          それから四、五人手を...            P
2              R3S3_CV_KENJI_GINGA.txt          ところが先生は早くも...            P
...
198            R3S3_DIFF_KAWABATA_SHINJU.txt    そして彼女達の...                  N
...
============== ================================ ================================== ==============

.. code-block :: none
	:caption: csv形式サンプルデータ(例)　text(小説の一部)　label(P:宮沢賢治作品, N:その他)
	
	index,tag1,text,label
	0,R3S3_CV_KENJI_GINGA.txt,一　午後の授業。「では...,P
	1,R3S3_CV_KENJI_GINGA.txt,それから四、五人手を...,P
	2,R3S3_CV_KENJI_GINGA.txt,　ところが先生は...,P
	...
	198,R3S3_DIFF_KAWABATA_SHINJU.txt,　そして彼女達の...,N
	...

事前学習
=========

| 整形済みのテキストデータを学習し、予測モデルに解析対象のテキストデータに含まれる単語の意味を学習させる作業です。
| TDLが提供するプリセットモデルは既に大量の日本語テキストデータを事前学習済みであるため、一般的な文書を解析する場合、本作業は不要です。
| 専門文書や社内文書など一般的でない単語が含まれるテキストデータを解析する場合は事前学習を実施したほうが、高精度な解析をすることが可能です。

| なお、ここでは本作業を省略します。実行する場合は :ref:`pre_train1` をご覧ください。


分類学習の実行
=============================

| 学習データ(*examples/sample_data/classification/train.csv*)を用いて、文書分類学習を実行します。

設定ファイルを準備する
-----------------------------
| 分類学習コマンドコンフィグファイルを準備します。
| ここでは事前に準備した *./examples/config/classification_train.json* を使用します。

| 設定ファイル上でepoch数やロードするモデルのパス、出力先のパスなどを指定できます。
| 今回は、TDLが提供しているpresetモデルを読み込み、学習を行うよう設定されています。

.. code-block :: none
	:caption: classification_train.json

	{
	  "data": {
	    "train": {
	      "text": {
	        "file": "examples/sample_data/classification/train.csv",
	        "index": "index",
	        "column": "text"
	      },
	      "label": {
	        "file": "examples/sample_data/classification/train.csv",
	        "index": "index",
	        "column": "label"
	      }
	    },
	    "valid": {
	      "text": {
	        "file": null,
	        "index": "index",
	        "column": "text"
	      },
	      "label": {
	        "file": null,
	        "index": "index",
	        "column": "label"
	      }
	    }
	  },
	  "model": {
	    "load": {
	      "dir": "cl-tohoku/bert-base-japanese-whole-word-masking"
	    },
	    "save": {
	      "dir": "./examples/classification_train/"
	    },
	    "train": {
	      "num_epochs": 5,
	      "batch_size": 32,
	      "max_seq_length": 64,
	      "learning_rate": 5e-05
	    },
	    "earlystop": {
	      "patience": null,
	      "min_delta": 1e-03
	    }
	  },
	  "task": {
	    "classification": {
	      "categories": null
	    }
	  }
	}


分類学習コマンドを実行する
---------------------------------

| 学習データを用いて分類予測モデルを作成します。その際、実行スクリプトとして *classification_train.rpd* を指定します。

| jupyter notebookのセルから以下のコマンドを実行します。

::

	! pyrapid /opt/nec/pyrapid/template/DMA/classification_train.rpd --config ./examples/config/classification_train.json
	

| コマンド実行に成功すると標準出力に文書分類学習の進捗状況が表示されます。

| コマンドが完了すると、 *examples/classification_train/* に以下のファイルが出力されます。

* 文書分類用予測モデルファイル
* ログファイル
* 文書分類学習コンフィグファイル

| 以上で、文書分類学習(予測モデルの作成)は完了です。



分類予測の実行
=============================

| テストデータと予測モデルを用いて予測を実行します。

| 学習していない未知のテキストデータ(*examples/sample_data/classification/predict.csv*)に文書分類用予測モデルを適用します。本作業は、学習が正常に完了していることが前提となります。

設定ファイルを準備する
-----------------------------

| 分類予測コマンドコンフィグファイルを準備します。
| ここでは事前に準備した *./examples/config/classification_predict.json* を使用します。

.. code-block :: none
	:caption: classification_predict.json

	{
	  "data": {
	    "predict": {
	      "text": {
	        "file": "./examples/sample_data/classification/predict.csv",
	        "index": "index",
	        "column": "text"
	      },
	      "label": {
	        "file": "./examples/sample_data/classification/predict.csv",
	        "index": "index",
	        "column": "label"
	      }
	    }
	  },
	  "model": {
	    "load": {
	      "dir": "./examples/classification_train/"
	    },
	    "predict": {
	      "batch_size": 32,
	      "max_seq_length": 64
	    }
	  },
	  "result": {
	    "save": {
	      "dir": "./examples/classification_predict/",
	      "attention_csv": false,
	      "attention_html": false
	    }
	  }
	}


分類予測コマンドを実行する
-----------------------------------

| 分類予測モデルを用いて予測を実行します。その際、実行スクリプトとして *classification_predict.rpd* を指定します。

| jupyter notebookのセルから以下のコマンドを実行します。

::

	! pyrapid /opt/nec/pyrapid/template/DMA/classification_predict.rpd --config ./examples/config/classification_predict.json

| コマンド実行に成功すると文書分類予測の進捗状況が表示されます。

| コマンドが完了すると、 *examples/classification_predict/* に以下のファイルが出力されます。

* 分類結果ファイル
* 分類精度ファイル
* 分類混同行列ファイル
* ログファイル
* 文書分類予測コンフィグファイル

| 各ファイルの内容については *NEC Advanced Analytics –テキスト分析 with Deep Learning V1.1 コマンドリファレンスガイド* の「文書分類予測コマンド」の節を参照してください。


| 例として予測結果の分類結果ファイルを以下に示します。
| 各indexに対しての予測結果がpredicted列に示されていることが確認できます。
| その他の列は各カテゴリの所属確率を示しています。

============== =========== ============================ ============================
index          predicted   N                            P
============== =========== ============================ ============================
0              P           6.530345854116604e-05        0.9999346733093262
1              P           4.7809226089157164e-05       0.9999521970748901
2              P           5.570322537096217e-05        0.9999443292617798
...
198            N           0.9999481439590454           5.1825390983140096e-05
...
============== =========== ============================ ============================


| 以上で、予測は完了となります。


.. _pre_train1:

【参考】事前学習
===================
| 本作業では事前学習を省略しましたが、実行する場合は以下の手順に従います。
| 詳細は *NEC Advanced Analytics -テキスト分析 with Deep Learning V1.1ユーザガイド* をご覧ください。

設定ファイルを準備する
---------------------------------

| 事前学習コマンドコンフィグファイルを準備します。
| 参考として *./examples/config/bert_pretrain.json* が用意されています。

.. code-block :: none
	:caption: bert_pretrain.json
	
	{
	  "data": {
	    "train": {
	      "text": {
	        "file": "./examples/sample_data/classification/train.csv",
	        "index": "index",
	        "column_a": "text",
	        "column_b": "text_b"
	      }
	    },
	    "valid": {
	      "text": {
	        "file": null,
	        "index": "index",
	        "column_a": "text_a",
	        "column_b": "text_b"
	      }
	    }
	  },
	  "model": {
	    "load": {
	      "dir": "cl-tohoku/bert-base-japanese-whole-word-masking"
	    },
	    "save": {
	      "dir": "./examples/bert_pretrain/"
	    },
	    "train": {
	      "num_epochs": 5,
	      "batch_size": 32,
	      "max_seq_length": 64,
	      "learning_rate": 5e-05
	    },
	    "early_stop": {
	      "patience": null,
	      "min_delta": 1e-03
	    }
	  },
	  "task": {
	    "method": "mlm"
	  }
	}



事前学習コマンドを実行する
-------------------------------------


jupyter notebookのセルから以下のコマンドを実行します。

::
	
	! pyrapid /opt/nec/pyrapid/template/DMA/bert_pretrain.rpd --config ./examples/config/bert_pretrain.json

| コマンド実行に成功すると事前学習の進捗状況が表示されます。
| コマンドが完了すると、*examples/bert_pretrain/* に以下のファイルが出力されます。

* 予測モデルファイル
* ログファイル
* BERT事前学習コンフィグファイル 


| 以上で、事前学習は完了です。
| 事前学習したモデルを利用するには *classification_train.json* ファイルを編集し、作成したモデルのパスを指定する必要があります。

