Skip to content

Latest commit

 

History

History
279 lines (195 loc) · 13.4 KB

README_jp.md

File metadata and controls

279 lines (195 loc) · 13.4 KB
メタツリーモデルに対するアルゴリズムがAISTATS 2025に採択！詳細はこちら！

Your First Library for Bayesian Machine Learning

BayesMLは，ベイズ統計学やベイズ決定理論に基づく機械学習の教育，研究，活用を促進し，社会に広く貢献することを目的としたライブラリです．

特徴

  • すぐ使える:
    • 定義済みのベイズ統計モデルをインポートするだけで利用できます．PyMCやStanのようにモデルを自分で定義する必要はありません．
  • ベイズ決定理論に基づくAPI:
    • ライブラリのAPIがベイズ決定理論に基づく意思決定の構造と対応しています．ベイズ決定理論は，パラメータ推定や新規データの予測など，幅広い意思決定を統一的に取り扱うためのフレームワークです．そのため，BayesMLでは，scikit-learnなどで採用されているfit-predict型のAPIよりも幅広い意思決定を直感的な操作で実現できます．（多くのモデルにはfit-predict関数も実装されています．）
  • モデル可視化関数:
    • 2~3次元空間上で，データ生成確率モデル，生成された人工データ，学習された事後分布を可視化するメソッドが全てのパッケージに備わっています．そのため，人工データの生成と学習を通じて確率モデル，アルゴリズムの特性を効果的に把握することができます．
  • 共役事前分布を利用した高速アルゴリズム:
    • 学習アルゴリズムの多くはデータ生成確率モデルと事前分布の共役性を効果的に用いた厳密計算法や変分ベイズ法を採用しているため，汎用的なMCMC法と比べて非常に高速で，オンライン学習にも適しています．一部のアルゴリズムではMCMC法を採用していますが，その場合も共役性を活かしてモデル毎に専用開発されたMCMC法を採用しています．

詳細はWebサイトをご覧ください．

ニュース

  • メタツリーモデルに対するアルゴリズムがAISTATS 2025に採択されました．詳細は以下のリンク先を御覧ください．

インストール

以下のコマンドによりインストール可能です．

pip install bayesml

BayesMLの実行には以下が必要です．

  • Python (>= 3.7)
  • NumPy (>= 1.20)
  • SciPy (>= 1.7)
  • MatplotLib (>= 3.5)
  • Scikit-learn (>= 1.1)

チュートリアル

BayesMLの各モデルには大きく2つのクラスがあります．一つは，事前分布や事後分布からのパラメータ生成や，データ生成に利用できるGenModelです．もう一つは，データからの事後分布の推定や予測分布の計算に利用できるLearnModelです．それぞれが，ベイズ決定理論に即したAPIを備えています．linearregressionモデルを例に，それぞれの使い方を見てみましょう．

GenModelによる人工データ生成

まずはライブラリをインポートします．

import numpy as np
from bayesml import linearregression

次に，データ生成確率モデルのインスタンスを作成します．ここでは，モデルの定数として（定数項を含む）回帰係数の次元c_degree=2を，パラメータとして回帰係数theta_vec = np.array([1,1]), 雑音項の精度（分散の逆数）tau = 10を指定しています．

gen_model = linearregression.GenModel(
    c_degree = 2, # degree
    theta_vec = np.array([1,1]), # coefficients
    tau = 10, # noise precision
)

以下のメソッドによって作成されたモデルの特徴を可視化できます．

gen_model.visualize_model()

Output:
theta_vec:
[1. 1.]
tau:
10.0
png

サンプルを生成し，変数x, yに保存するには以下のメソッドを用います．

x,y = gen_model.gen_sample(sample_size=100)

後で利用するためにテスト用のデータも生成しておきましょう．

x_test,y_test = gen_model.gen_sample(sample_size=100)

LearnModelによる学習と意思決定

LearnModelを用いて，先ほど生成したデータからモデルを学習してみましょう．

もちろん，LearnModelに与えことのできるデータはGenModelから生成したデータに限りません．様々な実データを分析することができます．

まずは学習用モデルのインスタンスを作成します．ここではモデルの定数として次数c_degree = 2だけを指定しています．他に，事前分布のハイパーパラメータを設定することもできます．

learn_model = linearregression.LearnModel(
    c_degree = 2, # degree
)

LearnModelにはパラメータの事後分布を可視化する関数が実装されています．この時点でパラメータの事後分布を可視化すると，まだデータからの学習を行っていないので事前分布が表示されます．

learn_model.visualize_posterior()

Output:
png

データからの学習によって事後分布を更新するには，以下のメソッドを用います．

learn_model.update_posterior(x,y)

更新された事後分布を可視化すると，事後分布の密度がx, yを生成するときに用いた真のパラメータの近くに移動していることがわかります．

learn_model.visualize_posterior()

Output:
png

学習されたモデルに基づいてパラメータ推定や新規データの予測などの意思決定を行うには，以下のようにします．

パラメータ推定を行うためには，estimate_paramsメソッドを用います．lossオプションをsquaredに指定することで，二乗誤差損失関数に基づくベイズリスク関数を最小にする推定値が得られます．得られる値はパラメータの事後分布の期待値となります．

learn_model.estimate_params(loss="squared",dict_out=True)

Output:
{'theta_vec': array([0.99846525, 0.96263024]), 'tau': 6.9036925167513195}

lossオプションをabsに指定すると，絶対誤差損失関数に基づくベイズリスク関数を最小にする推定値が得られます．得られる値はパラメータの事後分布の中央値となるため，tauの推定値が先程と異なっています．

learn_model.estimate_params(loss="abs",dict_out=True)

Output:
{'theta_vec': array([0.99846525, 0.96263024]), 'tau': 6.858623148933392}

新規データに対する予測値を出力するためには，まず以下のメソッドを用いて新規説明変数に対する予測分布を計算します．

learn_model.calc_pred_dist(x_test)

次に，make_predictionメソッドを用いることで，予測値が得られます．パラメータ推定の場合と同様，lossオプションを指定することで損失関数を指定できます．（ただし，今回の例では事後予測分布が左右対称であるため，二乗誤差損失を仮定した場合も絶対誤差損失を仮定した場合も同じ予測値が出力されます．）

y_pred = learn_model.make_prediction(loss="squared")

平均二乗誤差を計算してみましょう．

mse = np.sum((y_test - y_pred)**2) / len(y_test)
print(f"MSE: {mse}")

Output:
MSE: 0.09020880284291456

データ生成に用いた雑音項の精度（分散の逆数）が10であったことを踏まえると，十分な精度で予測できていることがわかります．

GenModelによる事後分布からのサンプリング

GenModelはLearnModelで学習した事後分布からパラメータをサンプリングしたり，事後予測分布から新規データをサンプリングしたりするためにも利用できます．

まず，LearnModelによって学習された事後分布のハイパーパラメータは以下のように取得できます．

hn_params = learn_model.get_hn_params()
print(hn_params)

Output:
{'hn_mu_vec': array([0.99846525, 0.96263024]), 'hn_lambda_mat': array([[ 99.87503339, 5.96145913],[ 5.96145913, 101. ]]), 'hn_alpha': 51.0, 'hn_beta': 7.387351026461872}

これをGenModelに渡すことで，事後分布からパラメータをサンプリングできます．

パラメータサンプリング用のGenModelインスタンスを新たに作成し，set_h_paramsメソッドを通してハイパーパラメータを渡します．（以下では辞書型であるhn_paramsの値hn_params.values()を*でアンパックして渡しています．これはBayesMLの機能ではなく，Pythonの機能です．）

posterior_gen_model = linearregression.GenModel(
    c_degree = 2, # degree
)
posterior_gen_model.set_h_params(*hn_params.values())

gen_paramsメソッドを用いてパラメータを生成し，get_paramsメソッドを用いて生成されたパラメータを取得します．複数回のサンプリングを行いたい場合は以下をfor文で繰り返してください．

posterior_gen_model.gen_params()
print(posterior_gen_model.get_params())

Output:
{'theta_vec': array([1.00935782, 0.93804208]), 'tau': 5.50775630793475}

事後予測分布から新規データをサンプリングしたい場合，パラメータのサンプリングに続いてデータを生成してください．「GenModelによる人工データ生成」で人工データを生成した際にはgen_sampleの引数に説明変数を与えませんでしたが，以下のように明示的に指定することもできます．

posterior_gen_model.gen_params()
_,y_new = posterior_gen_model.gen_sample(x=x_test[:10])
print(f"y_new: {y_new}")

Output:
y_new: [-0.49532975 2.03473075 1.13758759 -0.46735058 -0.71902336 -0.09288005 0.89463227 2.07886012 2.81211771 1.60020635]

パッケージ一覧

現在，以下のモデルに関するパッケージが利用可能です．本ライブラリでは，データ生成確率モデル，事前分布，事後分布（または近似事後分布），予測分布（または近似予測分布）を合わせてモデルと呼んでいます．

また，今後はより複雑な階層的モデルを取り扱うパッケージを追加していく予定です．

コントリビューションの方法

BayesMLへのコントリビューションを考えてくださってありがとうございます．詳細についてはこちらをご覧ください．

参照方法

学術的な成果にBayesMLをご利用いただく際は以下の文献参照をお示しいただければ幸いです．

プレーンテキスト

Y. Nakahara, N. Ichijo, K. Shimada, Y. Iikubo, 
S. Saito, K. Kazama, T. Matsushima, BayesML Developers, ``BayesML,'' 
Python package version 0.3.1, 
[Online] https://github.com/bayesml/BayesML

BibTeX

@misc{bayesml,
  author = {Nakahara, Yuta and Ichijo, Naoki and Shimada, Koshi and
            Iikubo, Yuji and Saito, Shota and Kazama, Koki and
            Matsushima, Toshiyasu and {BayesML Developers}},
  title = {{BayesML}},
  howpublished = {Python package version 0.3.1},
  note = {\url{https://github.com/bayesml/BayesML}},
  year = {2025}
}