river

River は、オンライン機械学習のための Python ライブラリです。ストリーミングデータに対する機械学習を、最もユーザーフレンドリーに行えるライブラリを目指しています。River は、creme と scikit-multiflow の合併により生まれました。

⚡️ クイックスタート

簡単な例として、ロジスティック回帰を訓練してウェブサイトフィッシングデータセットを分類してみましょう。以下はデータセットの最初の観測値です。

>>> from pprint import pprint
>>> from river import datasets

>>> dataset = datasets.Phishing()

>>> for x, y in dataset:
...     pprint(x)
...     print(y)
...     break
{'age_of_domain': 1,
 'anchor_from_other_domain': 0.0,
 'empty_server_form_handler': 0.0,
 'https': 0.0,
 'ip_in_url': 1,
 'is_popular': 0.5,
 'long_url': 1.0,
 'popup_window': 0.0,
 'request_from_other_domain': 0.0}
True

では、モデルをストリーミング方式でデータセットに対して実行してみましょう。予測とモデルの更新を順番に交互に行います。その間に、パフォーマンスメトリクスを更新して、モデルの出来栄えを確認します。

>>> from river import compose
>>> from river import linear_model
>>> from river import metrics
>>> from river import preprocessing

>>> model = compose.Pipeline(
...     preprocessing.StandardScaler(),
...     linear_model.LogisticRegression()
... )

>>> metric = metrics.Accuracy()

>>> for x, y in dataset:
...     y_pred = model.predict_one(x)      # make a prediction
...     metric.update(y, y_pred)           # update the metric
...     model.learn_one(x, y)              # make the model learn

>>> metric
Accuracy: 89.28%

もちろん、これは単なる人為的な例です。より詳しいチュートリアルについては、ドキュメントのはじめにのセクションをぜひご覧ください。

🛠 インストール

River は Python 3.11 以降 での動作を想定しています。インストールは pip で行えます：

pip install river

Linux、MacOS、Windows 向けのホイールが用意されています。つまり、ほとんどの場合、River をソースからビルドする必要はないでしょう。

River のコアとなるオンラインインターフェース（learn_one / predict_one）には pandas の依存関係はありません。ミニバッチインターフェース（learn_many、predict_many、predict_proba_many、transform_many）は pandas 上に構築されており、オプトイン方式です：

pip install "river[pandas]"

最新の開発版は GitHub から次のようにインストールできます：

pip install git+https://github.com/online-ml/river --upgrade
pip install git+ssh://[email protected]/online-ml/river.git --upgrade  # using SSH

この方法では、お使いのマシンに Cython と Rust がインストールされている必要があります。

🔮 機能

River は、次のアルゴリズムファミリーのオンライン実装を提供します：

• 多様なオプティマイザを備えた線形モデル
• 決定木とランダムフォレスト
• （近似）最近傍法
• 異常検知
• ドリフト検知
• レコメンダーシステム
• 時系列予測
• バンディット
• 因子化マシン
• 不均衡学習
• クラスタリング
• バギング/ブースティング/スタッキング
• 能動学習

River は、その他のオンラインユーティリティも提供します：

• 特徴抽出と選択
• オンライン統計とメトリクス
• 前処理
• 組み込みデータセット
• プログレッシブモデル検証
• モデルパイプライン

包括的な概要については、API をご確認ください。

🤔 River を使うべきでしょうか？

自分がオンライン機械学習を必要としているかどうかを自問してみてください。答えはおそらく「いいえ」です。ほとんどの場合、バッチ学習で十分に役割を果たします。オンラインアプローチが適しているのは、次のような場合です：

• 過去のデータに再度アクセスすることなく、新しいデータから学習できるモデルが必要な場合。
• コンセプトドリフトにロバストなモデルが必要な場合。
• 通常はイベントベースである本番環境の状況に近い形でモデルを開発したい場合。

River の特徴としては、次のようなものがあります：

• パフォーマンスよりも、明確さとユーザーエクスペリエンスに重点を置いています。
• 一度に1つのサンプルを処理するのが非常に高速です。試してみれば、すぐに分かるでしょう。
• Python エコシステムの他の部分ともうまく連携します。

🔗 便利なリンク

• ドキュメント
• パッケージリリース
• awesome-online-machine-learning
• GAIA での2022年プレゼンテーション
• Online Clustering: Algorithms, Evaluation, Metrics, Applications and Benchmarking（KDD'22 より）。

👐 コントリビューション

どのような形でもお気軽にご貢献ください。新しいアイデアやアプローチを常に歓迎しています。

• ご質問やお問い合わせがあれば、ディスカッションを開いてください。非公開のメールを送るよりも、公開の場で質問する方が有益です。また、貢献する前にディスカッションを開くことも推奨されます。全員の認識を合わせ、無駄な作業を避けるためです。
• バグやパフォーマンスの問題を発見したと思われる場合は、イシューを開くことを歓迎します。
• 私たちのロードマップは公開されています。目に留まったものに取り組んだり、提案を送ったりしてください。

コードベースに変更を加えたい場合は、コントリビューションガイドラインをご確認ください。

🤝 提携

💬 引用

River がお役に立ち、学術出版物で引用したい場合は、JMLR に掲載された論文を参照してください：

@article{montiel2021river,
  title={River: machine learning for streaming data in Python},
  author={Montiel, Jacob and Halford, Max and Mastelini, Saulo Martiello
          and Bolmier, Geoffrey and Sourty, Raphael and Vaysse, Robin and Zouitine, Adil
          and Gomes, Heitor Murilo and Read, Jesse and Abdessalem, Talel and others},
  year={2021}
}

📝 ライセンス

River は、3条項BSDライセンスの下で提供されるフリーかつオープンソースのソフトウェアです。