戻る

Example

まず、サンプルプログラムを http://www.wpi-aimr.tohoku.ac.jp/hiraoka_labo/homcloud/download/homcloud-examples.zip からダウンロードします。解凍すると homcloud-examples というディレクトリが作成され、その中にテーマ毎のサブディレクトリとしてそれぞれのサンプルが入っています。 各サンプルのディレクトリに移動し、

./run.sh

run.sh を実行する、または README.ja.md 内の記述にしたがって操作することで動作が確認できます(一部、README.ja.md を含まないサンプルもあります)。 初心者向けのサンプルとして pointcloud(点配列からパーシステント図の作成), binary_picture(二値画像からパーシステント図の作成), grayscale_picture(グレイスケール画像からパーシステント図の作成) があります。 初めてお使いになる場合はこの3つからお試しください。 基本的な使い方に慣れたら、パーシステント図のベクトル化 vectorize-pdと機械学習のサンプル(pca , ml)などへおすすみください。

また、基本プログラムのチュートリアルが http://www.wpi-aimr.tohoku.ac.jp/hiraoka_labo/homcloud/basic-usage.htmlにありますのでそちらもご参考ください。

目次


Homeに戻る このページのトップへ戻る

共通のデータ

Homcloud ではパーシステント図作成の途中の処理によってできる中間データファイルや、 図を作成するためのデータファイルなどに共通の形式を用いています。 ここではそれらについて説明をします。 付属のサンプルでは、主に元データからまず icomplex ファイルを作成し、続いて idiagram ファイルを作成して、パーシステント図を作成するようになっています。icomplex、idiagram についての説明は以下に書いてあります。

|入力データ| → | icomplex | → | idiagram | → |パーシステント図|

データ構造に関する、より詳細な説明は データの入出力 のページをご覧ください。

dipha によって生成される中間データファイル icomplex

dipha によって出力される、リトルエンディアンで書かれたバイナリ形式のファイルです。 homcloud ではパーシステント図を作る前の中間ファイルとして利用されます。 サンプルプログラムでは、拡張子が icomplex として出力しています。 matlab などを使う場合は直接この icomplex のファイルを読み書きします。 詳しくは dipha のウェブサイト dipha をご覧ください。

パーシステント図を作成するためのデータファイル diagram

パーシステント図を作るために中間ファイルです。 homcloud で提供するサンプルでは下のインデックスつきの idiagram を使います。

パーシステント図を高速に作成するためのデータファイル idiagram

diagram ファイルにインデックスの情報を追加したバイナリ形式のファイルになります。 パーシステント図を作るために中間ファイルです。 サンプルプログラムでは、拡張子が idiagram として出力しています。 diagram ファイルからパーシステント図を作成する場合には dipha によって計算が必要になりますが、 idiagram ファイルを使うことで、より高速な処理ができます。

パーシステント図作成用データをテキストへダンプしたデータファイル

idiagram のデータはフィルタリングのプログラム( homcloud.dump_diagram )を使うことで、テキストデータとしてダンプができます。 二次利用する場合などにお使いください。 サンプルプログラムでは、ホモロジーの次数の数を前につけて、拡張子が txt として出力しています。

(例) output.0.txt 0次のデータ
     output.1.txt 1次のデータ
     output.2.txt 2次のデータ

これらのファイルには、それぞれの次元の穴の生成時刻(1列目)、消滅時刻(2列目)、{生成子}、{消滅子}として情報が書かれています. テキスト形式であるため、エディター等で内部を確認することができます。

例えば、0次のホモロジーの計算結果のデータをダンプしたテキストファイルの中身は、以下の様になっています。

b1 d1 {(x_b11,y_b11,z_b11),(x_b12,y_b12,z_b12)} {(x_d11,y_d11,z_d11),(x_d12,y_d12,z_d12),(x_d13,y_d13,z_d13)}
b2 d2 {(x_b21,y_b21,z_b21),(x_b22,y_b22,z_b22)} {(x_d21,y_d21,z_d21),(x_d22,y_d22,z_d22),(x_d23,y_d23,z_d23)}
...

ここで

を表しています.

共通の可視化プログラム

idiagram ファイルから共通の可視化プログラムによってパーシステント図を作成することができます。 コマンドラインから処理する homcloud-plot_PD と対話的にグラフを表示する homcloud-plot_PD_gui があります。

homcloud-plot_PD では引数として描画範囲や、領域の分割数、出力ファイル名などを与えます。 homcloud-plot_PD_gui は実行後にGUIが起動し、描画範囲や分割数などは後から変更して再描画できます。 詳しくはコマンドリファレンスの homcloud-plot_PDhomcloud-plot_PD_gui の項を参考にしてください。

(例)
python3 -m homcloud.plot_PD -d 0 -x "[-20.5:20.5]" -X 41 -l -o output.0.png output.idiagram
python3 -m homcloud.plot_PD_gui -d 1 -x "[-20.5:20.5]" -X 41 output.idiagram

pointcloud


この例題はポイントクラウドデータに対するホモロジーを計算し(homcloud-pc2diphacomplex)、パーシステント図のデータを計算します(homcloud-dipha)。

計算されたデータからパーシステント図の描画(homcloud-plot-PD,homcloud-plot-PD-gui)や関連するデータを出力します(homcloud-dump-diagramhomcloud.query_full_ph_tree)。

入力データ

input.txt

一様乱数によって生成された、三次元の5000個のデータ点です。 generator.py によって作成しています。

例題の動かしかた

./run.sh

で以下のファイルが生成されます。

各種GUIの使い方

まず、あらかじめrun.shを動かして、output.idiagram を生成しておいてから、以下のプログラムを動かしてください。

plot_PD_gui (パーシステント図をインタラクティブに表示)

可視化プログラムの homcloud-plot-PD-gui をより簡単に使うためのシェルスクリプト、plot_PD_gui.sh (windows版は plot_PD_gui.bat )が用意されています。

./plot_PD_gui.sh 1

引数の 0 はホモロジーの次数(0 or 1 or 2)です。 コマンドの詳細は plot_PD_gui.sh の中身を確認してください。


Homeに戻る このページのトップへ戻る

binary_picture

2値画像から「太らせる/痩せさせる」ことによるパーシステンスや関連するデータを計算します (homcloud-pict-binarize)。 ここでは入力する画像データの二値化も同時に行うことができます。 ユーザーは白黒を色分けする閾値を指定します(-t 閾値)。 また、白と黒のどちらを「太らせる/痩せさせる」かを、 -m black-base または -m white-baseで選ぶことができます。

入力データ

二値化された画像を入力データとして使います。

input.png

例題の動かしかた

ターミナルからシェルスクリプトを実行します。

./run.sh

実行後に以下のファイルが生成されます。

各種GUIの使い方

まず、あらかじめ run.sh を動かして、output.idiagram を生成しておいてから、以下のプログラムを動かしてください。

plot_PD_gui (パーシステント図をインタラクティブに表示)

可視化プログラムの homcloud-plot-PD-gui をより簡単に使うためのシェルスクリプト、plot_PD_gui.sh (windows版は plot_PD_gui.bat )が用意されています。

./plot_PD_gui.sh 0

引数の 0 はホモロジーの次数(0 or 1)です。 コマンドの詳細は plot_PD_gui.sh の中身を確認してください。

view_index_pict_gui (birth/death pixel を描画)

./view_index_pict_gui.sh 0

0 は上と同じでホモロジーの次数(0 or 1)

bi di (x_bi y_bi) (x_di y_di)

grayscale_picture


この例題はグレイスケール画像を閾値を変化させることによるパーシステンスや関連するデータを計算します。

入力データ

input.png

例題の動かしかた

./run.sh

で以下のファイルが生成されます。

各種GUIの使い方

まず、あらかじめrun.shを動かして、sublevel.idiagram および superlevel.idiagramを生成しておいてから、以下のプログラムを動かしてください。

plot_PD_gui (パーシステント図をインタラクティブに表示)

可視化プログラムの homcloud-plot-PD-gui をより簡単に使うためのシェルスクリプト、plot_PD_gui.sh (windows版は plot_PD_gui.bat )が用意されています。

 ./plot_PD_gui.sh 0 sublevel

0 はホモロジーの次数(0 or 1)、 sublevel は閾値を変化させる向き (superlevel or sublevel) です。

view_index_pict_gui (birth/death pixel を描画)

 ./view_index_pict_gui.sh 0 sublevel

0 はホモロジーの次数(0 or 1) sublevel は閾値を変化させる向き (superlevel or sublevel)

右側の数値の説明

(bi di)- (x_bi, y_bi)(x_di, y_di)

左の絵の説明


Homeに戻る このページのトップへ戻る

binary_3d_picture


現在、編集中です。

Homeに戻る このページのトップへ戻る

grayscale_3d


現在、編集中です。

Homeに戻る このページのトップへ戻る

partial


現在、編集中です。

実行方法

./run.sh

入力データ

data.txt 1列目、2列目がx, y座標で3列目がグループ名

出力データ


Homeに戻る このページのトップへ戻る

pca

パーシステント図の主成分分析のサンプルです。

picts/ ディレクトリにある画像100枚と labels.txt (これはpcaの結果を表示するための赤青の色分けのために使います)です。

例の動かしかた

まず、PDを計算してベクトル化します。

sh compute-pd-vectorize-pd.sh

すると、diagrams/ 以下にPD(拡張子.idiagram)が生成され、 vects/以下にPIでベクトル化したPD(拡張子.txt)が生成されます。

つぎに PCA を計算します。

   python3 pca.py

すると mean.txtpc1.txtpc2.txt (それぞれ、平均、1st principal component、2nd principal componentです) が生成されます。また、実行時にターミナルへ表示されるのは主成分の寄与率です。また、入力データを2次元に落としたデータ(pca.txt)も生成されます。

pca.txt は以下のコマンドで可視化できます。

  python3 plot_pca.py

labels.txt の 0-1 情報はここでの色付けで使われます。

また、principal componentをPDの形で可視化するには以下のコマンドでOKです。

sh show_pc.sh mean.txt # 平均成分を表示
sh show_pc.sh pc1.txt # 1st PCを表示
sh show_pc.sh pc2.txt # 2nd PCを表示

Homeに戻る このページのトップへ戻る

tree-for-image


現在、編集中です。

Homeに戻る このページのトップへ戻Zる

vectorize-pd


パーシステント図をベクトル化します。

まずは入力データとして、点配列の input.txt からパーシステント図のデータ(output.idiagram)を作成します。

python3 -m homcloud.pc2diphacomplex -d 3 --no-square -I input.txt input.icomplex
python3 -m homcloud.dipha input.icomplex output.idiagram

確認のため、どのようなパーシステント図になるかを

python3 -m homcloud.plot_PD -d 1 -l -x "0:0.5" -X 64 -o pd.png output.idiagram

で可視化してもよいでしょう。

python3 -m homcloud.vectorize_PD -d 1 -x "0:0.5" -X 64 -D 0.008 -C 30 -p 3.0 -H histoinfo.json -o vector.txt output.idiagram

を実行することによって、パーシステント図のデータは (64^2)x1次元のベクトルへ変換され、vectors.txt というテキストファイルに保存されます。 ベクトル化と同時に、

D: セル値をガウス関数を使って周辺にぼかすための標準偏差
C: 対角線近くのセル値を減らすための距離の閾値
p: セル値のべき乗をとるためのインデックス

というパラメータの強度を引数で指定し、これによってパーシステント図のセルの値は変更されます。 この変換は主に機械学習の前処理として行います。 vectorize_PD のより詳細な使い方は

python3 -m homcloud.vectorize_PD -h

でご確認ください。

histoinfo.json はベクトル化されたデータをもとのパーシステント図に戻すための情報が含まれているファイルです。

python3 -m homcloud.view_vectorized_PD vector.txt histoinfo.json -o vectorized-pd.png

によってベクトル化された後のデータで再構築した vectorized-pd.png によって確認ができます。view_vectorized_PD によるパーシステント図の再構築は機械学習の結果から構造の逆解析の時にも使います。

Homeに戻る このページのトップへ戻る

ml

3種類の入力データによる、機械学習についてのサンプルが含まれています。

入力データ

data-1 #2値画像
data-2 #2次元点配列
data-3 #2値画像、目的変数のデータ付き

例題の動かし方

まずは PCA (主成分分析)を以下のような手順やってみましょう

次は同じデータで分類問題をやりましょう

その他の課題など

総合的課題

PCAの解析の例
Classificationの解析の例
linear regression

Homeに戻る このページのトップへ戻る