Merge pull request #70 from tsukuba-websci/nanami/update/README

Update: READMEを更新する

README.md

@@ -3,16 +3,20 @@
 Iwahashi, Okabe and Suda's experiments for MPS-TOM 2023
 
 ## Abstract
-エージェントベースの壺モデルの探索手法(全探索,GA,QD)の比較を行うリポジトリです。
+情報処理学会論文誌:数理モデル化と応用に投稿した論文に関するリポジトリです。
+
+エージェントベースの壺モデルの探索手法(全探索,ランダムサーチ,GA,QD)の比較を行います。
 - [**`data/`**](/data/)
   - 探索に用いるターゲットデータ
 - [**`full-search/`**](/full-search/)
-  - 全探索を行うスクリプト
+  - 既存モデルの全探索を行うスクリプト
+- [**`random-search/`**](/random-search/)
+  - ランダムサーチによる探索を行うスクリプト
 - [**`ga/`**](/ga/)
   - 遺伝的アルゴリズムによる探索を行うスクリプト
-- [**`qd`**](/qd/)
+- [**`qd/`**](/qd/)
   - Quality Diversityによる探索を行うスクリプト
-- [**`visualize`**](/visualize/)
+- [**`visualize/`**](/visualize/)
   - 探索結果をもとに可視化するスクリプト
 
 ## Requirements
@@ -23,7 +27,7 @@ Iwahashi, Okabe and Suda's experiments for MPS-TOM 2023
 - Rust (latest)
   - Rustの実行環境があれば問題ありません
 
-`full-search/`,`ga/`,`qd/`から上位のディレクトリ`lib/`の中身をimportするためにpoetryを用いて設定しています。依存関係は`$ poetry install`でインストールしてください。
+`full-search/`,`random-search/`,`ga/`,`qd/`から上位のディレクトリ`lib/`の中身をimportするためにpoetryを用いて設定しています。依存関係は`$ poetry install`でインストールしてください。
 
 
 ## Usage
@@ -36,7 +40,7 @@ julia --proj=. --threads=auto make_synthetic_target.jl
 $$(\rho,\nu,s)=(5,5,SSW),(5,5,WSW),(5,15,SSW),(5,15,WSW),(20,7,SSW),(20,7,WSW)$$
 
 ### Search　Params
-各ディレクトリ`full-search/`,`ga/`,`qd/`のREADMEの指示に従って、`main.py`及び`main.jl`を実行してください。
+各ディレクトリ`full-search/`,`random-search/`,`ga/`,`qd/`のREADMEの指示に従って、`main.py`及び`main.jl`を実行してください。
 #### Required Files
 - `./data/aps.csv`
 - `./data/twitter.csv`
@@ -47,6 +51,7 @@ $$(\rho,\nu,s)=(5,5,SSW),(5,5,WSW),(5,15,SSW),(5,15,WSW),(20,7,SSW),(20,7,WSW)$$
 #### Required Files
 - `./data/...`
 - `./full-search/results/...`
+- `./random-search/results/...`
 - `./ga/results/...`
 - `./qd/results/...`
 

full-search/README.md

@@ -1,12 +1,15 @@
+# 既存モデルの全探索によるパラメタ探索
+
 ## 概要
-既存モデルである全探索を行います。
+既存モデルの全探索を行います。
 rho,nu=1,2,...,20と戦略SSW,WSWの2種類の全てのパラメータ組(20x20x2=800)で全探索します。
-それぞれUbaldiのモデルを走らせ、10個の指標を計測して保存します。
+それぞれUbaldiのモデルを走らせ、10個の指標を計測して保存します。その後にターゲットデータとの距離を計算します。
 
-GA,QDはターゲットデータに合うように(rho,nu,s)を探索しますが、`full-search/main.jl`ではターゲットデータを意識していません。
-壺モデルを走らせる処理と10個の指標の計測が終わっていれば、ターゲットデータとのフィッティング（ターゲットデータとのdistanceを求め、最低な(rho,nu,s)を見つける操作）は一瞬で完了するため、`/visualize`で可視化するときに行われています。
+GA,QDはターゲットデータに合うように(rho,nu,s)を探索しますが、`full-search/main.jl`ではターゲットデータを意識せず、ネットワークの生成と10個の指標の計測だけを行います。
+ターゲットデータとのフィッティング（ターゲットデータとのdistanceを求め、最良の(rho,nu,s)を見つける操作）は`fitting.py`で行われます。
 
 ## 実行方法
+Ubaldiのモデルを走らせ、10個の指標を計算して保存するには、以下のコマンドを実行してください。
 ```bash
 $ julia --proj=. --threads=auto main.jl
 ```
@@ -18,4 +21,10 @@ $ julia --proj=. --threads=auto main.jl
 rho,nu,s,gamma,no,nc,oo,oc,c,y,g,r,h
 <int>,<int>,<string>,<float>,<float>,<float>,<float>,<float>,<float>,<float>,<float>,<float>,<float>
 ...
-```
+```
+
+次に以下のコマンドを実行してください。`./results/existing_full_search.csv`を用いて、各ターゲットデータとの距離を計算できます。
+```bash
+$ python fitting.py <target_type>
+```
+この結果は`./results/<target>/archive.csv`に保存されます。

ga/README.en.md

@@ -12,7 +12,7 @@ Contains the source code to perform a parameter search of the urn-model using th
 
 Parameter search by genetic algorithm is carried out in the following steps:
 
-1. randomly generate a population with a vector representing the parameters: `(rho, nu, friendship, recentness)` for each individual.
+1. randomly generate a population with a vector representing the parameters: `(rho, nu, recentness, frequency)` for each individual.
 2. run the urn-model based on the parameters, calculate the goodness of fit from the results and record this
 3. perform an evolutionary calculation of the population based on the goodness of fit
     a. Select individuals with high goodness of fit and perform crossover
@@ -24,7 +24,7 @@ Parameter search by genetic algorithm is carried out in the following steps:
 
 In particular, the goodness of fit required in 2 (for each individual) is specifically calculated as follows:
 
-1. run the urn-model based on the parameters (`rho`, `nu`, `friendship`, `recentness`)
+1. run the urn-model based on the parameters (`rho`, `nu`, `recentness`, `frequency`)
 2. record the "history of interactions" generated by the execution of the urn-model
 3. compute 10 metrics that characterise the network using the history recorded in 2.
 4. calculate the difference between the metrics of the target network and those calculated in 3, multiplied by -1, as the goodness of fit

ga/README.md

@@ -12,7 +12,7 @@
 
 遺伝的アルゴリズムによるパラメタ探索は、以下のような手順で行われます。
 
-1. パラメタを表すベクトル: `(rho, nu, friendship, recentness)` を各個体とする集団をランダムに生成する
+1. パラメタを表すベクトル: `(rho, nu, recentness, frequency)` を各個体とする集団をランダムに生成する
 2. パラメタをもとに壺モデルを実行、その結果から適合度を算出し、これを記録する
 3. 適合度をもとに、集団の進化計算を行う
     a. 適合度が高い個体を選択し、交叉を行う
@@ -24,7 +24,7 @@
 
 特に2で（各個体ごとに）求められる適合度は、具体的には以下のようにして求められます。
 
-1. (`rho`, `nu`, `friendship`, `recentness`) というパラメタをもとに、壺モデルを実行する
+1. (`rho`, `nu`, `recentness`, `frequency`) というパラメタをもとに、壺モデルを実行する
 2. 壺モデルの実行によって生成された「相互やり取りの履歴」を記録する
 3. 2で記録した履歴を用いて、ネットワークの特徴を示す10個のメトリクスを計算する
 4. ターゲットとしているネットワークのメトリクスと、3で計算したメトリクスとの間の差分を計算し、これに-1をかけたものを適合度とする

qd/README.md

@@ -4,7 +4,7 @@
 
 Quality Diversity（QD）による壺モデルのパラメータ探索を行うソースコード一式が含まれています。
 
-この探索には、[pyribs](https://pyribs.org) というQDのライブラリを使用しています。探索空間はCVT-MAP-Elitesと呼ばれる手法によって固定数のセルに分割されており、今回はセル数を500に設定しています。探索空間の軸であるbehavioral descriptorには、壺モデルで生成されたネットワークをgraph2vecで128次元のベクトルに変換して使用しています。したがって、探索空間はgraph2vecによって生成されるベクトルの値域が[-5, 5]の128次元に設定されています。
+この探索には、[pyribs](https://pyribs.org) というQDのライブラリを使用しています。探索空間はCVT-MAP-Elitesと呼ばれる手法によって固定数のセルに分割されています。探索空間の軸であるbehavioral descriptor(BD)には、壺モデルで生成されたネットワークをgraph2vecで変換して使用しており、値域は[-5,5]です。
 
 
 ## 実行方法
@@ -14,23 +14,25 @@ Quality Diversity（QD）による壺モデルのパラメータ探索を行う
 ```bash
 $ python make_model.py
 ```
+BDに用いられる64,128,256次元のgraph2vecのモデルが作成されます。
 
 ### QDによる探索
 このディレクトリ（`/qd`）に移動した上で，`main.py` を実行してください。
+次元数は`make_model.py`で設定した64,128,256次元のいずれかを指定してください。
 
 ```bash
 $ pwd # => /path/to/qd
-$ python main.py {twitter,aps,synthetic} [rho] [nu] [{SSW,WSW}]
+$ python main.py {twitter,aps,synthetic} <dim> <cells> [rho] [nu] [{SSW,WSW}]
 ```
 
 実行例を以下に示します。
-ターゲットデータが実データ(twitter)の場合：
+ターゲットデータが実データ(twitter)でBDが128次元、分割するセル数が500の場合：
 ```bash
-$ python main.py twiiter
+$ python main.py twiiter 128 500
 ```
-ターゲットデータが合成データ(rho,nu,s)=(5,5,SSW)の場合：
+ターゲットデータが合成データ(rho,nu,s)=(5,5,SSW)でBDが64次元、分割するセル数が750の場合の場合：
 ```bash
-$ python main.py synthetic 5 5 SSW
+$ python main.py synthetic 64 750 5 5 SSW
 ```
 
 実行を行うと，`./results/{twitter,aps,synthetic}` 以下に結果が保存されます。その中に各世代ごとのアーカイブデータと，最終的な結果が保存されます。
@@ -45,3 +47,16 @@ rho,nu,recentness,frequency,distance
 rho,nu,recentness,frequency,distance
 <float>,<float>,<float>,<float>,<float>
 ```
+
+### ハイパーパラメータチューニング
+ターゲットデータごとに適したセル数,graph2vecで表現する次元数を探索する場合は、`tuning.py`を実行してください。
+```bash
+$ python tuning.py <target_data>  [rho] [nu] [s]
+```
+結果は`./results/hyperparams-search/<target>/cells<cells>/dim<dim>`以下に`main.py`の結果と同じ形式で保存されます。`tuning.py`の実行には時間がかかるため、注意してください。
+
+チューニングした結果から最適なパラメータを見つけ、可視化できるようにするには、`copy_best.py`を実行してください。
+```bash
+$ python copy_best.py <target_data>  [rho] [nu] [s]
+```
+`results/hyperparams/`にある各ハイパーパラメータでの結果から、最良のものが`results/`にコピーされます。

random-search/README.md

@@ -0,0 +1,34 @@
+# ランダムサーチによるパラメタ探索
+
+## 概要
+パラメータのランダムサーチを行います。
+決められた`rho,nu,recentness,frequency`の範囲でランダムに遺伝子を生成する。
+生成した遺伝子で壺モデルを一定回数実行し、遺伝子パラメータと10個の指標を保存する。
+
+GA,QDはターゲットデータに合うように`(rho,nu,s)`を探索しますが、`randome-search/main.py`ではターゲットデータを意識していません。
+ターゲットデータとのフィッティング（ターゲットデータとのdistanceを求め、最良の`(rho,nu,s)`を見つける操作）は`fitting.py`で行われます。
+
+## 実行方法
+10個の指標を計算して保存するには、以下のコマンドを実行してください。
+```bash
+$ python main.py
+```
+この結果は`./results/random-search.csv`に以下の形式で保存されます。
+```
+rho,nu,recentness,frequency,gamma,no,nc,oo,oc,c,y,g,r,h
+<int>,<int>,<float>,<float>,<float>,<float>,<float>,<float>,<float>,<float>,<float>,<float>,<float>,<float>
+...
+```
+
+
+次に以下のコマンドを実行してください。`./results/random-search.csv`を用いて、各ターゲットデータとの距離を計算できます。
+```bash
+$ python fitting.py <target_type>
+```
+全ての出力結果は`./results/<target>/archive.csv`に以下のような形式で出力されます。
+また、最もdistanceが小さいパラメータの情報は`best.csv`に出力されます。
+```
+rho,nu,recentness,frequency,distance
+<float>,<float>,<float>,<float>,<float>
+```
+

visualize/README.md

@@ -1,35 +1,79 @@
-# full searh, GA, QDの実験結果の可視化
+# 既存モデルの全探索, ランダムサーチ, GA, QDの実験結果の可視化
 
 ## 概要
 
-以下の3種類の図を作成する。
-- 棒グラフ
-- レーダーチャート
+以下の5種類の図と2種類の表を出力するソースコードです。
+
+図を生成するスクリプトは`/graphs`にあります。
+- 箱ひげ図
+  - `box.py`
+  - full-search,random-search,GA,QD
+  - Fig.3(A), Fig.5(A)
 - タイムライン
+  - `timeline.py`
+  - GA,QD
+  - Fig.3(B), Fig.5(B)
+- レーダーチャート
+  - `radar_chart.py`
+  - full-search,GA,QD
+  - Fig.4, Fig.6
+- ネットワークのベクトルが作るマップ
+  - `map.py`
+  - GA,QDの実データ
+  - Fig.7
+- 棒グラフ
+  - `bar_graph.py`
+  - full-search,random-search,GA,QD
+
+表を生成するスクリプトは`/tables`にある。
+- 最良個体の距離の平均と分散を示す表
+  - `print_best.py`
+  - full-search,random-search,GA,QD
+  - Table1, Table2
+- 最良の遺伝子5つを示すlatex形式の表
+  - `latex_table.py`
+  - QD
+  - Table3
+
 
 ## 実行方法
 
 ### 前処理
-GA,QDで見つけた最良のrho,nu,recentness,frequencyの組で壺モデルを10回走らせます。
+GA,QD,ランダムサーチで見つけた最良の`(rho,nu,recentness,frequency)`の組で壺モデルを10回走らせます。（既存モデルの全探索では初めから10回走らせているため、ここでは行いません）
 ```bash
 $ pwd # => /path/to/visualize
 $ python preprocessing.py <target_type>
 ```
-この結果は`./results/fitted`に保存され、棒グラフ・レーダーチャートの生成に用いられます。
+この結果は`./results/fitted`に保存され、棒グラフ・レーダーチャート、最良個体の距離の表の生成に用いられます。
+
+
+GA,QDの最終的な全個体のに対して、壺モデルを回してネットワークを生成します。そのネットワークをgraph2vecしたベクトルを保存しておきます。
+```bash
+$ python make_vec.py <target_type>
+```
+この結果は`./results/vec`に保存され、ネットワークのベクトルが作るマップに用いられます。
+
+
 
 ### 可視化のスクリプト
+図を出力する場合:
 ```bash
 $ pwd # => /path/to/visualize
 $ python main.py <graph_type> <target_type>
 ```
-
 各引数の詳細などは `python main.py -h` あるいは `python main.py --help` で確認できます。
 実行を行うと，`./results` 以下にグラフの種類ごとに分けられて結果が保存されます。
 
-また、latex形式で遺伝子の表を出力するには、以下のコマンドを実行してください。
+
+最良個体の距離の平均と分散を示す表を出力する場合:
+```bash
+$ python tables/print_best.py <target_type>
+```
+
+latex形式で遺伝子の表を出力する場合：
 ```bash
 $ pwd # => /path/to/visualize
 $ python graphs/latex_table.py
 ```
-`MPS-TOM-urnmodel/`で用意されているpoetry環境では、このスクリプトだけpandasのversionの依存関係が合わないため、動きません。
+`MPS-TOM-urnmodel/`で用意されているpoetry環境では、`latex_table.py`だけ`pandas`のversionの依存関係が合わないため、動きません。
 `pandas>=1.5.3`, `Jinja2>=3.0.0`, `matplotlib`, `numpy`のある環境で実行してください。