In a nutshell
River is a Python library for online machine learning. It is the result of a merger between creme and scikit-multiflow. River's ambition is to be the go-to library for doing machine learning on streaming data.
Table of contents
-
β‘οΈ Quickstart -
π Installation -
π§ Philosophy -
π₯ Features -
π Useful links -
ποΈ Media -
π Contributing -
β€οΈ They've used us -
π€ Affiliations -
π¬ Citation -
π License
β‘οΈ
Quickstart
As a quick example, we'll train a logistic regression to classify the website phishing dataset. Here's a look at the first observation in the dataset.
>>> 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
Now let's run the model on the dataset in a streaming fashion. We sequentially interleave predictions and model updates. Meanwhile, we update a performance metric to see how well the model is doing.
>>> 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 = metric.update(y, y_pred) # update the metric
... model = model.learn_one(x, y) # make the model learn
>>> metric
Accuracy: 89.20%
π
Installation
River is intended to work with Python 3.6 or above. Installation can be done with pip:
pip install river
There are wheels available for Linux, MacOS, and Windows, which means that you most probably won't have to build River from source.
You can install the latest development version from GitHub as so:
pip install git+https://github.com/online-ml/river --upgrade
Or, through SSH:
pip install git+ssh://[email protected]/online-ml/river.git --upgrade
π§
Philosophy
Machine learning is often done in a batch setting, whereby a model is fitted to a dataset in one go. This results in a static model which has to be retrained in order to learn from new data. In many cases, this isn't elegant nor efficient, and usually incurs a fair amount of technical debt. Indeed, if you're using a batch model, then you need to think about maintaining a training set, monitoring real-time performance, model retraining, etc.
With River, we encourage a different approach, which is to continuously learn a stream of data. This means that the model process one observation at a time, and can therefore be updated on the fly. This allows to learn from massive datasets that don't fit in main memory. Online machine learning also integrates nicely in cases where new data is constantly arriving. It shines in many use cases, such as time series forecasting, spam filtering, recommender systems, CTR prediction, and IoT applications. If you're bored with retraining models and want to instead build dynamic models, then online machine learning (and therefore River!) might be what you're looking for.
Here are some benefits of using River (and online machine learning in general):
- Incremental: models can update themselves in real-time.
- Adaptive: models can adapt to concept drift.
- Production-ready: working with data streams makes it simple to replicate production scenarios during model development.
- Efficient: models don't have to be retrained and require little compute power, which lowers their carbon footprint
- Fast: when the goal is to learn and predict with a single instance at a time, then River is an order of magnitude faster than PyTorch, Tensorflow, and scikit-learn.
π₯
Features
- Linear models with a wide array of optimizers
- Nearest neighbors, decision trees, naΓ―ve Bayes
- Progressive model validation
- Model pipelines as a first-class citizen
- Anomaly detection
- Recommender systems
- Time series forecasting
- Imbalanced learning
- Clustering
- Feature extraction and selection
- Online statistics and metrics
- Built-in datasets
- And much more
π
Useful links
ποΈ
Media
- PyData Amsterdam 2019 presentation (slides, video)
- Toulouse Data Science Meetup presentation
- Machine learning for streaming data with creme
- Hong Kong Data Science Meetup presentation
π
Contributing
Feel free to contribute in any way you like, we're always open to new ideas and approaches. You can also take a look at the issue tracker and the icebox to see if anything takes your fancy. Please check out the contribution guidelines if you want to bring modifications to the code base. You can view the list of people who have contributed here.
β€οΈ
They've used us
These are companies that we know have been using River, be it in production or for prototyping.
Feel welcome to get in touch if you want us to add your company logo!
π€
Affiliations
Sponsors
Collaborating institutions and groups
π¬
Citation
If river has been useful for your research and you would like to cite it in an scientific publication, please refer to this paper:
@misc{2020river,
title={River: machine learning for streaming data in Python},
author={Jacob Montiel and Max Halford and Saulo Martiello Mastelini
and Geoffrey Bolmier and Raphael Sourty and Robin Vaysse
and Adil Zouitine and Heitor Murilo Gomes and Jesse Read
and Talel Abdessalem and Albert Bifet},
year={2020},
eprint={2012.04740},
archivePrefix={arXiv},
primaryClass={cs.LG}
}
π
License
River is free and open-source software licensed under the 3-clause BSD license.
4k Jan 2, 2023
21.8k Jan 9, 2023
8.9k Dec 30, 2022
81 Nov 26, 2022
3 Feb 25, 2022
447 Jan 3, 2023
87 Dec 12, 2022
1.5k Dec 27, 2022
457 Jan 3, 2023
52 Nov 14, 2022
45 Dec 8, 2022
87 Dec 28, 2022
32 Dec 18, 2022
86 Dec 28, 2022
34 Oct 26, 2022
83 Dec 14, 2022
114 Dec 28, 2022
26 Sep 22, 2022
89 Dec 18, 2022