Merge branch 'develop' into develop-contexttree-GenModel

Author: yuta-nakahara

bayesml/_check.py

@@ -1,6 +1,8 @@
 # Code Author
 # Yuta Nakahara <yuta.nakahara@aoni.waseda.jp>
 # Yuji Iikubo <yuji-iikubo.8@fuji.waseda.jp>
+# Yasushi Esaki <esakiful@gmail.com>
+# Jun Nishikawa <jun.b.nishikawa@gmail.com>
 import numpy as np
 
 _EPSILON = np.sqrt(np.finfo(np.float64).eps)
@@ -179,6 +181,14 @@ def float_vec_sum_1(val,val_name,exception_class):
             return val
     raise(exception_class(val_name + " must be a 1-dimensional numpy.ndarray, and the sum of its elements must equal to 1."))
 
+def float_vecs_sum_1(val,val_name,exception_class):
+    if type(val) is np.ndarray:
+        if np.issubdtype(val.dtype,np.integer) and val.ndim >= 1 and np.all(np.abs(np.sum(val, axis=-1) - 1.) <= _EPSILON):
+            return val.astype(float)
+        if np.issubdtype(val.dtype,np.floating) and val.ndim >= 1 and np.all(np.abs(np.sum(val, axis=-1) - 1.) <= _EPSILON):
+            return val
+    raise(exception_class(val_name + " must be a numpy.ndarray whose ndim >= 1, and the sum along the last dimension must equal to 1."))
+
 def int_(val,val_name,exception_class):   
     if np.issubdtype(type(val),np.integer):
         return val
@@ -205,3 +215,9 @@ def onehot_vecs(val,val_name,exception_class):
         if np.issubdtype(val.dtype,np.integer) and val.ndim >= 1 and np.all(val >= 0) and np.all(val.sum(axis=-1)==1):
             return val
     raise(exception_class(val_name + " must be a numpy.ndarray whose dtype is int and whose last axis constitutes one-hot vectors."))
+
+def shape_consistency(val: int, val_name: str, correct: int, correct_name: str, exception_class):
+    if val != correct:
+        message = (f"{val_name} must coincide with {correct_name}: "
+                   + f"{val_name} = {val}, {correct_name} = {correct}")
+        raise(exception_class(message))

bayesml/base.py

@@ -257,13 +257,21 @@ def load_hn_params(self,filename):
             +'or ``LearnModel.save_hn_params()``.')
             )
 
-    @abstractmethod
     def reset_hn_params(self):
-        pass
-
-    @abstractmethod
+        """Reset the hyperparameters of the posterior distribution to their initial values.
+        
+        They are reset to the output of `self.get_h0_params()`.
+        Note that the parameters of the predictive distribution are also calculated from them.
+        """
+        self.set_hn_params(*self.get_h0_params().values())
+    
     def overwrite_h0_params(self):
-        pass
+        """Overwrite the initial values of the hyperparameters of the posterior distribution by the learned values.
+        
+        They are overwitten by the output of `self.get_hn_params()`.
+        Note that the parameters of the predictive distribution are also calculated from them.
+        """
+        self.set_h0_params(*self.get_hn_params().values())
 
     @abstractmethod
     def update_posterior(self):

doc/devdoc/abstract_class.md

@@ -1,6 +1,6 @@
 <img src="../logos/BayesML_logo.png" width="200">
 
-# 抽象クラス概要 Ver.4
+# 抽象クラス概要 Ver.5
 <div style="text-align:right">
 作成：中原
 </div>
@@ -10,7 +10,7 @@
 データ生成観測確率モデルとその事前分布の抽象基底クラス．GenModelクラスに継承することで，以下の名前のメソッドの実装を強いる．
 
 * `def set_h_params(self):`
-  * 事前分布のハイパーパラメータを設定するためのメソッド．入力されたハイパーパラメータが理論上の仮定（分散共分散行列の正定値性等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．GenModelの`get_h_params()`，LearnModelの`get_h0_params()`, `get_hn_params()`で得られる辞書の順序と位置引数の順序を揃えるようにする．Python 3.7以降では辞書の要素の順序が保持されるようになったため，これにより`genmodel.set_h_params(*learnmodel.get_hn_params().vaules())`といったアンパック渡しの機能を活かした使い方が可能となる．
+  * 事前分布のハイパーパラメータを設定するためのメソッド．`c_`で始まる変数は変更しなくてよく，それに整合しない場合はエラーを返す．入力されたハイパーパラメータが理論上の仮定（分散共分散行列の正定値性等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．GenModelの`get_h_params()`，LearnModelの`get_h0_params()`, `get_hn_params()`で得られる辞書の順序と位置引数の順序を揃えるようにする．Python 3.7以降では辞書の要素の順序が保持されるようになったため，これにより`genmodel.set_h_params(*learnmodel.get_hn_params().vaules())`といったアンパック渡しの機能を活かした使い方が可能となる．
 * `def get_h_params(self):`
   * 事前分布のハイパーパラメータを返すメソッド．ハイパーパラメータ名をキーとする辞書を返す．
 * `def save_h_params(self):`（抽象クラスではない）
@@ -39,7 +39,7 @@
 データ生成観測確率モデルのパラメータ事後分布の抽象基底クラス．LearnModelクラスに継承することで以下のメソッドの実装を強いる．
 
 * `def set_h0_params(self):`
-  * 事後分布のハイパーパラメータの初期値を設定するためのメソッド（`reset_hn_params()`を呼ぶことで，`hn_`で始まる事後分布ハイパーパラメータや`p_`で始まる予測分布パラメータも同時に初期化する）．入力されたハイパーパラメータが理論上の仮定（分散共分散行列の正定値性等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．GenModelの`get_h_params()`，LearnModelの`get_h0_params()`, `get_hn_params()`で得られる辞書の順序と位置引数の順序を揃えるようにする．Python 3.7以降では辞書の要素の順序が保持されるようになったため，これにより`learnmodel.set_h_params(*genmodel.get_hn_params().vaules())`といったアンパック渡しの機能を活かした使い方が可能となる．
+  * 事後分布のハイパーパラメータの初期値を設定するためのメソッド（`reset_hn_params()`を呼ぶことで，`hn_`で始まる事後分布ハイパーパラメータや`p_`で始まる予測分布パラメータも同時に初期化する）．`c_`で始まる変数は変更しなくてよく，それに整合しない場合はエラーを返す．入力されたハイパーパラメータが理論上の仮定（分散共分散行列の正定値性等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．GenModelの`get_h_params()`，LearnModelの`get_h0_params()`, `get_hn_params()`で得られる辞書の順序と位置引数の順序を揃えるようにする．Python 3.7以降では辞書の要素の順序が保持されるようになったため，これにより`learnmodel.set_h_params(*genmodel.get_hn_params().vaules())`といったアンパック渡しの機能を活かした使い方が可能となる．
 * `def get_h0_params(self):`
   * 事後分布のハイパーパラメータの初期値を返すメソッド．ハイパーパラメータ名をキーとする辞書を返す．
 * `def save_h0_params(self):`（抽象クラスではない）
@@ -49,17 +49,17 @@
 * `def get_hn_params(self):`
   * データに基づいて更新された事後分布のハイパーパラメータを返すメソッド．ハイパーパラメータ名をキーとする辞書を返す．
 * `def set_hn_params(self):`
-  * 更新後の事後分布のハイパーパラメータを直接設定するためのメソッド（`calc_pred_dist()`を用いて`p_`で始まる予測分布パラメータも同時に初期化する）．入力されたハイパーパラメータが理論上の仮定（分散共分散行列の正定値性等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．GenModelの`get_h_params()`，LearnModelの`get_h0_params()`, `get_hn_params()`で得られる辞書の順序と位置引数の順序を揃えるようにする．Python 3.7以降では辞書の要素の順序が保持されるようになったため，これにより`learnmodel.set_h_params(*genmodel.get_hn_params().vaules())`といったアンパック渡しの機能を活かした使い方が可能となる．
+  * 更新後の事後分布のハイパーパラメータを直接設定するためのメソッド（`calc_pred_dist()`を用いて`p_`で始まる予測分布パラメータも同時に初期化する）．`c_`で始まる変数は変更しなくてよく，それに整合しない場合はエラーを返す．入力されたハイパーパラメータが理論上の仮定（分散共分散行列の正定値性等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．GenModelの`get_h_params()`，LearnModelの`get_h0_params()`, `get_hn_params()`で得られる辞書の順序と位置引数の順序を揃えるようにする．Python 3.7以降では辞書の要素の順序が保持されるようになったため，これにより`learnmodel.set_h_params(*genmodel.get_hn_params().vaules())`といったアンパック渡しの機能を活かした使い方が可能となる．
 * `def save_hn_params(self):`（抽象クラスではない）
   * データに基づいて更新された事後分布のハイパーパラメータをファイルに保存するメソッド．`get_hn_params(self):`さえ正しく実装されていれば汎用的に機能するよう`bayesml/base.py`に実装済みなので，基本的に個別のモデルでオーバーライドする必要はない．
 * `def load_hn_params(self):`（抽象クラスではない）
   * `save_hn_params`で保存したハイパーパラメータを読み込んで`set_hn_params`で設定するメソッド．`get_hn_params(self):`さえ正しく実装されていれば汎用的に機能するよう`bayesml/base.py`に実装済みなので，基本的に個別のモデルでオーバーライドする必要はない．
-* `def reset_hn_params(self):`
-  * 更新後の事後分布ハイパーパラメータ（`hn_`で始まるハイパーパラメータの値）を初期値（`h0_`で始まるハイパーパラメータの値）に設定し直すメソッド．`calc_pred_dist()`を用いて`p_`で始まる予測分布パラメータも同時に初期化する．
-* `def overwrite_h0_params(self):`
-  * 事後分布のハイパーパラメータの初期値（`h0_`で始まるハイパーパラメータの値）を更新後の事後分布ハイパーパラメータ（`hn_`で始まるハイパーパラメータの値）で上書きするメソッド．`calc_pred_dist()`を用いて`p_`で始まる予測分布パラメータも同時に初期化する．
+* `def reset_hn_params(self):`（抽象クラスではない）
+  * 更新後の事後分布ハイパーパラメータ（`hn_`で始まるハイパーパラメータの値）を初期値（`h0_`で始まるハイパーパラメータの値）に設定し直すメソッド．`get_h0_params(self):`, `set_hn_params(self):`さえ正しく実装されていれば汎用的に機能するよう`bayesml/base.py`に実装済みなので，基本的に個別のモデルでオーバーライドする必要はない．
+* `def overwrite_h0_params(self):`（抽象クラスではない）
+  * 事後分布のハイパーパラメータの初期値（`h0_`で始まるハイパーパラメータの値）を更新後の事後分布ハイパーパラメータ（`hn_`で始まるハイパーパラメータの値）で上書きするメソッド．`get_hn_params(self):`, `set_h0_params(self):`さえ正しく実装されていれば汎用的に機能するよう`bayesml/base.py`に実装済みなので，基本的に個別のモデルでオーバーライドする必要はない．
 * `def update_posterior(self):`
-  * データに基づいて事後分布のハイパーパラメータを更新するためのメソッド．データは引数として渡し，変数として保持しない．データが理論上の仮定（整数かどうか等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．
+  * データに基づいて事後分布のハイパーパラメータを更新するためのメソッド．in-placeな処理を心がける．データは引数として渡し，変数として保持しない．データが理論上の仮定（整数かどうか等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．
 * `def estimate_params(self):`
   * データに基づいて更新された事後分布を用いてパラメータを推定するためのメソッド．推定の評価基準をオプション`loss="criteria"`として指定することで，出力値が変わる．事後分布の種類によってはmodeが存在しない場合などもあるので，そういった場合には`None`を返し，警告を表示するようにする．
 * `def visualize_posterior(self):`
@@ -78,7 +78,7 @@
 * `def load_p_params(self):`（抽象クラスではない）
   * `save_p_params`で保存したハイパーパラメータを読み込んで`set_p_params`で設定するメソッド．`get_p_params(self):`さえ正しく実装されていれば汎用的に機能するよう`bayesml/base.py`に実装済みなので，基本的に個別のモデルでオーバーライドする必要はない． -->
 * `def calc_pred_dist(self):`
-  * 事後分布のハイパーパラメータと新規データから予測分布のパラメータを計算するためのメソッド．新規データが理論上の仮定（整数かどうか等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．
+  * 事後分布のハイパーパラメータと新規データから予測分布のパラメータを計算するためのメソッド．in-placeな処理を心がける．新規データが理論上の仮定（整数かどうか等）を満たさない時はエラーを返すようにする．よく使う入力値チェックは`bayesml/_check.py`に書いておく．
 * `def make_prediction(self):`
   * 予測分布を用いて新規データを予測するためのメソッド．予測の評価基準をオプション`loss="criteria"`として指定することで，出力値が変わる．予測分布の種類によってはmodeが存在しない場合などもあるので，そういった場合には`None`を返し，警告を表示するようにする．
 * `def pred_and_update(self):`