creme is a library for online machine learning, also known as incremental learning. Online learning is a machine learning regime where a model learns one observation at a time. This is in contrast to batch learning where all the data is processed in one go. Incremental learning is desirable when the data is too big to fit in memory, or simply when you want to handle streaming data. In addition to many online machine learning algorithms, creme provides utilities for extracting features from a stream of data.

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: models that work in development can naturally be brought into production.
• Efficient: models don't have to be retrained and require little compute power, which lowers their carbon footprint

Useful links

• Documentation
  • API reference
  • User guide
  • FAQ
  • Change history
• Benchmarks
• Issue tracker
• Package releases
• PyData Amsterdam 2019 presentation (slides, video)
• Toulouse Data Science presentation

Installation

☝️ creme is intended to work with Python 3.6 and above.

creme can simply be installed with pip.

pip install creme

You can also install the bleeding edge version as so:

pip install git+https://github.com/creme-ml/creme
# Or through SSH:
pip install git+ssh://[email protected]/creme-ml/creme.git

If you're looking to contribute to creme and want to have a development setup, then please check out the contribution guidelines.

Example

In the following example we'll use a linear regression to forecast the number of available bikes in bike stations from the city of Toulouse. Each observation looks like this:

>>> import pprint
>>> from creme import datasets

>>> X_y = datasets.ToulouseBikes()
>>> x, y = next(iter(X_y))

>>> pprint.pprint(x)
{'clouds': 75,
 'description': 'light rain',
 'humidity': 81,
 'moment': datetime.datetime(2016, 4, 1, 0, 0, 7),
 'pressure': 1017.0,
 'station': 'metro-canal-du-midi',
 'temperature': 6.54,
 'wind': 9.3}

>>> print(f'Number of bikes: {y}')
Number of bikes: 1

We will include all the available numeric features in our model. We will also use target encoding by calculating a running average of the target per station and hour. Before being fed to the linear regression, the features will be scaled using a StandardScaler. Note that each of these steps works in a streaming fashion, including the feature extraction. We'll evaluate the model by asking it to forecast 30 minutes ahead while delaying the true answers, which ensures that we're simulating a production scenario. Finally we will print the current score every 20,000 predictions.

>>> import datetime as dt
>>> from creme import compose
>>> from creme import datasets
>>> from creme import feature_extraction
>>> from creme import linear_model
>>> from creme import metrics
>>> from creme import model_selection
>>> from creme import preprocessing
>>> from creme import stats

>>> X_y = datasets.ToulouseBikes()

>>> def add_hour(x):
...     x['hour'] = x['moment'].hour
...     return x

>>> model = compose.Whitelister('clouds', 'humidity', 'pressure', 'temperature', 'wind')
>>> model += (
...     add_hour |
...     feature_extraction.TargetAgg(by=['station', 'hour'], how=stats.Mean())
... )
>>> model += feature_extraction.TargetAgg(by='station', how=stats.EWMean(0.5))
>>> model |= preprocessing.StandardScaler()
>>> model |= linear_model.LinearRegression()

>>> model_selection.progressive_val_score(
...     X_y=X_y,
...     model=model,
...     metric=metrics.MAE(),
...     on='moment',
...     delay=dt.timedelta(minutes=30),
...     print_every=30_000
... )
[30,000] MAE: 2.230049
[60,000] MAE: 2.290409
[90,000] MAE: 2.334638
[120,000] MAE: 2.315149
[150,000] MAE: 2.319982
[180,000] MAE: 2.335385
MAE: 2.338837

You can visualize the pipeline as so:

>>> model
Pipeline (
  TransformerUnion (
    Whitelister (
      whitelist=('clouds', 'humidity', 'pressure', 'temperature', 'wind')
    ),
    Pipeline (
      FuncTransformer (
        func="add_hour"
      ),
      TargetAgg (
        by=['station', 'hour']
        how=Mean ()
        target_name="target"
      )
    ),
    TargetAgg (
      by=['station']
      how=EWMean (
        alpha=0.5
      )
      target_name="target"
    )
  ),
  StandardScaler (
    with_mean=True
    with_std=True
  ),
  LinearRegression (
    optimizer=SGD (
      lr=InverseScaling (
        learning_rate=0.01
        power=0.25
      )
    )
    loss=Squared ()
    l2=0.
    intercept=9.742884
    intercept_lr=Constant (
      learning_rate=0.01
    )
    clip_gradient=1e+12
    initializer=Zeros ()
  )
)

We can also draw the pipeline.

>>> dot = model.draw()

By only using a few lines of code, we've built a robust model and evaluated it by simulating a production scenario. You can find a more detailed version of this example here. creme is a framework that has a lot to offer, and as such we kindly refer you to the documentation if you want to know more.

Contributing

Like many subfields of machine learning, online learning is far from being an exact science and so there is still a lot to do. Feel free to contribute in any way you like, we're always open to new ideas and approaches. If you want to contribute to the code base please check out the CONTRIBUTING.md file. Also take a look at the issue tracker and see if anything takes your fancy.

Last but not least you are more than welcome to share with us on how you're using creme or online learning in general! We believe that online learning solves a lot of pain points in practice, and would love to share experiences.

This project follows the all-contributors specification. Contributions of any kind are welcome!

Max Halford 📆 💻	AdilZouitine 💻	Raphael Sourty 💻	Geoffrey Bolmier 💻	vincent d warmerdam 💻	VaysseRobin 💻	Lygon Bowen-West 💻
Florent Le Gac 💻	Adrian Rosebrock 📝	Jovan Veljanoski 💻	Dimitri 💻	Gaurav Sharma 💻

License

See the license file.