bhaskarkvvsr / creme

🍨 Online machine learning in Python

creme is a Python library for online machine learning. All the tools in the library can be updated with a single observation at a time, and can therefore be used to learn from streaming data.

🤗 Merger announcement

TLDR

creme and scikit-multiflow are merging. A new package will result from this merge. Both development teams will work together on this new package.

Why?

We feel that both projects share the same vision. We believe that pooling our resources instead of duplicating work will benefit both sides. We are also confident that this will benefit both communities. There will be more people working on the new project, which will allow us to distribute work more efficiently. We will thus be able to work on more features and improve the overall quality of the project.

How does this affect each project?

Both projects will stop active development once the new package is released. The code for both projects will remain publicly available, although development will only focus on minor maintenance during a transition period. During this transition period, most of the functionality of both projects will be made available in the new package.

The architecture of the new package is more Pythonic. It will focus on single-instance incremental models. The new API reflects these changes.

Detailed information on the new architecture and API will be available with the release of the new package.

How does this affect users?

We encourage users to move towards the new package when possible. We understand that this transition will require an extra effort in the short term from current users. However, we believe that the result will be better for everyone in the long run.

You will still be able to install and use creme as well as scikit-multiflow. Both projects will remain on PyPI, conda-forge and GitHub.

When?

The target date for the first release: 2nd half of October 2020.

⚡️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 creme import datasets

>>> X_y = datasets.Phishing()  # this is a generator

>>> for x, y in X_y:
...     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 creme import compose
>>> from creme import linear_model
>>> from creme import metrics
>>> from creme import preprocessing

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

>>> metric = metrics.Accuracy()

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

>>> metric
Accuracy: 89.20%

🛠 Installation

creme is intended to work with Python 3.6 or above. Installation can be done with pip:

pip install creme

There are wheels available for Linux, MacOS, and Windows, which means that in most cases you won't have to build creme from source.

You can install the latest development version from GitHub as so:

pip install git+https://github.com/creme-ml/creme --upgrade

Or, through SSH:

pip install git+ssh://[email protected]/creme-ml/creme.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 creme, 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 creme!) might be what you're looking for.

Here are some benefits of using creme (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 creme is a 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

• Documentation
• Benchmarks
• Issue tracker
• Package releases

👁️ 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.

💬 Citation

Please use the following citation if you want to reference creme in a scientific publication:

@software{creme,
  title = {{creme}, a {P}ython library for online machine learning},
  author = {Halford, Max and Bolmier, Geoffrey and Sourty, Raphael and Vaysse, Robin and Zouitine, Adil},
  url = {https://github.com/creme-ml/creme},
  version = {0.6.1},
  date = {2020-06-10},
  year = {2019}
}

Note that in the future we will probably publish a dedicated research paper.

📝 License

creme is free and open-source software licensed under the 3-clause BSD license.