[PR #1008] [CLOSED] Add modAL #913

New Issue

GiteaMirror · 2025-11-06T13:05:15-06:00

GiteaMirror commented

2025-11-06 13:05:15 -06:00

📋 Pull Request Information

Original PR: https://github.com/vinta/awesome-python/pull/1008
Author: @cosmic-cortex
Created: 1/10/2018
Status: ❌ Closed

Base: master ← Head: add-modAL

📝 Commits (1)

708fd8e Add modAL

📊 Changes

1 file changed (+1 additions, -0 deletions)

View changed files

📝 README.md (+1 -0)

📄 Description

Modular Active Learning framework for Python3

Overview

Introduction
Active learning from bird's-eye view
modAL in action
Installation
About the developer

Introduction

modal: adjective, relating to structure as opposed to substance

(Merriam-Webster Dictionary)

modAL is an active learning framework for Python3, designed with modularity, flexibility and extensibility in mind. Built on top of scikit-learn, it allows you to rapidly create active learning workflows with nearly complete freedom. What is more, you can easily replace parts with your custom built solutions, allowing you to design novel algorithms with ease. modAL is aimed for practicioners and researchers as well, to make the assembly and testing of active learning pipelines quick and easy.

Active learning from bird's-eye view

With the recent explosion of available data, you have can have millions of unlabelled examples with a high cost to obtain labels. For instance, when trying to predict the sentiment of tweets, obtaining a training set can require immense manual labour. But worry not, active learning comes to the rescue! In general, AL is a framework allowing you to increase classification performance by intelligently querying you to label the most informative instances. In general, an active learning workflow looks like the following.

The key components of any workflow are the model you choose, the uncertainty measure you use and the query strategy you apply to request labels. With modAL, instead of choosing from a small set of built-in components, you have the freedom to seamlessly integrate scikit-learn or Keras models into your algorithm and easily tailor your custom query strategies and uncertainty measures.

Let's see what modAL can do for you!

From zero to one in a few lines of code

Active learning with a scikit-learn classifier, for instance RandomForestClassifier, can be as simple as the following.

from modAL.models import ActiveLearner
from sklearn.ensemble import RandomForestClassifier

# initializing the learner
learner = ActiveLearner(
    predictor=RandomForestClassifier(),
    X_initial=X_train, y_initial=y_train
)

# query for labels
query_idx, query_inst = learner.query(X_pool)

# ...obtaining new labels from the Oracle...

# supply label for queried instance
learner.teach(X_pool[query_idx], y_new)

Replacing parts quickly

If you would like to use different uncertainty measures and query strategies than the default uncertainty sampling, you can either replace them with several built-in strategies or you can design your own by following a few very simple design principles. For instance, replacing the default uncertainty measure to classification entropy looks the following.

from modAL.models import ActiveLearner
from modAL.uncertainty import entropy_sampling
from sklearn.ensemble import RandomForestClassifier

learner = ActiveLearner(
    predictor=RandomForestClassifier(),
    query_strategy=entropy_sampling,
    X_initial=X_train, y_initial=y_train
)

Replacing parts with your own solutions

modAL was designed to make it easy for you to implement your own query strategy. For example, implementing and using a simple random sampling strategy is as easy as the following.

import numpy as np

def random_sampling(classifier, X_pool):
    n_samples = len(X_pool)
    query_idx = np.random.choice(range(n_samples))
    return query_idx, X_pool[query_idx]

learner = ActiveLearner(
    predictor=RandomForestClassifier(),
    query_strategy=random_sampling,
    X_initial=X_train, y_initial=y_train
)

An example with active regression

To see modAL in real action, let's consider an active regression problem with Gaussian Processes! In this example, we shall try to learn the noisy sine function:

import numpy as np

X = np.random.choice(np.linspace(0, 20, 10000), size=200, replace=False).reshape(-1, 1)
y = np.sin(X) + np.random.normal(scale=0.3, size=X.shape)

For active learning, we shall define a custom query strategy tailored to Gaussian processes. In a nutshell, a query stategy in modAL is a function taking (at least) two arguments (an estimator object and a pool of examples), outputting the index of the queried instance and the instance itself. In our case, the arguments are regressor and X.

def GP_regression_std(regressor, X):
    _, std = regressor.predict(X, return_std=True)
    query_idx = np.argmax(std)
    return query_idx, X[query_idx]

After setting up the query strategy and the data, the active learner can be initialized.

from modAL.models import ActiveLearner
from sklearn.gaussian_process import GaussianProcessRegressor
from sklearn.gaussian_process.kernels import WhiteKernel, RBF

n_initial = 5
initial_idx = np.random.choice(range(len(X)), size=n_initial, replace=False)
X_initial, y_initial = X[initial_idx], y[initial_idx]

kernel = RBF(length_scale=1.0, length_scale_bounds=(1e-2, 1e3)) \
         + WhiteKernel(noise_level=1, noise_level_bounds=(1e-10, 1e+1))

regressor = ActiveLearner(
    predictor=GaussianProcessRegressor(kernel=kernel),
    query_strategy=GP_regression_std,
    X_initial=X_initial.reshape(-1, 1), y_initial=y_initial.reshape(-1, 1)
)

The initial regressor is not very accurate.

The blue band enveloping the regressor represents the standard deviation of the Gaussian process at the given point. Now we are ready to do active learning!

# active learning
n_queries = 10
for idx in range(n_queries):
    query_idx, query_instance = regressor.query(X)
    regressor.teach(X[query_idx].reshape(1, -1), y[query_idx].reshape(1, -1))

After a few queries, we can see that the prediction is much improved.

Additional examples

Including this, many examples are available:

Installation

modAL requires

Python >= 3.5
NumPy >= 1.13
SciPy >= 0.18
scikit-learn >= 0.18

You can install modAL directly with pip:

pip install modAL

Alternatively, you can install modAL directly from source:

pip install git+https://github.com/cosmic-cortex/modAL.git

For running the examples, Matplotlib >= 2.0 is recommended.

About the developer

modAL is developed by me, Tivadar Danka (aka cosmic-cortex in GitHub). I have a PhD in pure mathematics, but I fell in love with biology and machine learning right after I finished my PhD. I have changed fields and now I work in the Bioimage Analysis and Machine Learning Group of Peter Horvath, where I am working to develop active learning strategies for intelligent sample analysis in biology. During my work I realized that in Python, creating and prototyping active learning workflows can be made really easy and fast with scikit-learn, so I ended up developing a general framework for this. The result is modAL :) If you have any questions, requests or suggestions, you can contact me at 85a5187a@opayq.com! I hope you'll find modAL useful!

Anyone who agrees with this pull request could vote for it by adding a 👍 to it, and usually, the maintainer will merge it when votes reach 20.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/vinta/awesome-python/pull/1008 **Author:** [@cosmic-cortex](https://github.com/cosmic-cortex) **Created:** 1/10/2018 **Status:** ❌ Closed **Base:** `master` ← **Head:** `add-modAL` --- ### 📝 Commits (1) - [`708fd8e`](https://github.com/vinta/awesome-python/commit/708fd8e63841fbc6a94a0af03d0b9f0524b59d04) Add modAL ### 📊 Changes **1 file changed** (+1 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+1 -0) </details> ### 📄 Description <img src="https://cosmic-cortex.github.io/modAL/img/modAL_b.png" alt="modAL" style="width: 400px;"> Modular Active Learning framework for Python3 [![travis-ci-master](https://travis-ci.org/cosmic-cortex/modAL.svg?branch=master)](https://travis-ci.org/cosmic-cortex/modAL) [![codecov-master](https://codecov.io/gh/cosmic-cortex/modAL/branch/master/graph/badge.svg)](https://codecov.io/gh/cosmic-cortex/modAL) # Overview - [Introduction](#introduction) - [Active learning from bird's-eye view](#active-learning) - [modAL in action](#modAL-in-action) - [From zero to one in a few lines of code](#initialization) - [Replacing parts quickly](#replacing-parts) - [Replacing parts with your own solutions](#replacing-parts-with-your-own-solutions) - [An example with active regression](#active-regression) - [Additional examples](#working-examples) - [Installation](#installation) - [About the developer](#about-the-developer) # Introduction<a name="introduction"></a> > modal: adjective, relating to structure as opposed to substance > > (Merriam-Webster Dictionary) modAL is an active learning framework for Python3, designed with *modularity, flexibility* and *extensibility* in mind. Built on top of scikit-learn, it allows you to rapidly create active learning workflows with nearly complete freedom. What is more, you can easily replace parts with your custom built solutions, allowing you to design novel algorithms with ease. modAL is aimed for practicioners and researchers as well, to make the assembly and testing of active learning pipelines quick and easy. ## Active learning from bird's-eye view<a name="active-learning"></a> With the recent explosion of available data, you have can have millions of unlabelled examples with a high cost to obtain labels. For instance, when trying to predict the sentiment of tweets, obtaining a training set can require immense manual labour. But worry not, active learning comes to the rescue! In general, AL is a framework allowing you to increase classification performance by intelligently querying you to label the most informative instances. In general, an active learning workflow looks like the following. ![active-learning](https://cosmic-cortex.github.io/modAL/img/active_learning.png) The key components of any workflow are the **model** you choose, the **uncertainty** measure you use and the **query** strategy you apply to request labels. With modAL, instead of choosing from a small set of built-in components, you have the freedom to seamlessly integrate scikit-learn or Keras models into your algorithm and easily tailor your custom query strategies and uncertainty measures. # modAL in action<a name="modAL-in-action"></a> Let's see what modAL can do for you! ## From zero to one in a few lines of code<a name="initialization"></a> Active learning with a scikit-learn classifier, for instance RandomForestClassifier, can be as simple as the following. ```python from modAL.models import ActiveLearner from sklearn.ensemble import RandomForestClassifier # initializing the learner learner = ActiveLearner( predictor=RandomForestClassifier(), X_initial=X_train, y_initial=y_train ) # query for labels query_idx, query_inst = learner.query(X_pool) # ...obtaining new labels from the Oracle... # supply label for queried instance learner.teach(X_pool[query_idx], y_new) ``` ## Replacing parts quickly<a name="replacing-parts"></a> If you would like to use different uncertainty measures and query strategies than the default uncertainty sampling, you can either replace them with several built-in strategies or you can design your own by following a few very simple design principles. For instance, replacing the default uncertainty measure to classification entropy looks the following. ```python from modAL.models import ActiveLearner from modAL.uncertainty import entropy_sampling from sklearn.ensemble import RandomForestClassifier learner = ActiveLearner( predictor=RandomForestClassifier(), query_strategy=entropy_sampling, X_initial=X_train, y_initial=y_train ) ``` ## Replacing parts with your own solutions<a name="replacing-parts-with-your-own-solutions"></a> modAL was designed to make it easy for you to implement your own query strategy. For example, implementing and using a simple random sampling strategy is as easy as the following. ```python import numpy as np def random_sampling(classifier, X_pool): n_samples = len(X_pool) query_idx = np.random.choice(range(n_samples)) return query_idx, X_pool[query_idx] learner = ActiveLearner( predictor=RandomForestClassifier(), query_strategy=random_sampling, X_initial=X_train, y_initial=y_train ) ``` ## An example with active regression<a name="active-regression"></a> To see modAL in *real* action, let's consider an active regression problem with Gaussian Processes! In this example, we shall try to learn the *noisy sine* function: ```python import numpy as np X = np.random.choice(np.linspace(0, 20, 10000), size=200, replace=False).reshape(-1, 1) y = np.sin(X) + np.random.normal(scale=0.3, size=X.shape) ``` For active learning, we shall define a custom query strategy tailored to Gaussian processes. In a nutshell, a *query stategy* in modAL is a function taking (at least) two arguments (an estimator object and a pool of examples), outputting the index of the queried instance and the instance itself. In our case, the arguments are ```regressor``` and ```X```. ```python def GP_regression_std(regressor, X): _, std = regressor.predict(X, return_std=True) query_idx = np.argmax(std) return query_idx, X[query_idx] ``` After setting up the query strategy and the data, the active learner can be initialized. ```python from modAL.models import ActiveLearner from sklearn.gaussian_process import GaussianProcessRegressor from sklearn.gaussian_process.kernels import WhiteKernel, RBF n_initial = 5 initial_idx = np.random.choice(range(len(X)), size=n_initial, replace=False) X_initial, y_initial = X[initial_idx], y[initial_idx] kernel = RBF(length_scale=1.0, length_scale_bounds=(1e-2, 1e3)) \ + WhiteKernel(noise_level=1, noise_level_bounds=(1e-10, 1e+1)) regressor = ActiveLearner( predictor=GaussianProcessRegressor(kernel=kernel), query_strategy=GP_regression_std, X_initial=X_initial.reshape(-1, 1), y_initial=y_initial.reshape(-1, 1) ) ``` The initial regressor is not very accurate. ![gp-initial](https://cosmic-cortex.github.io/modAL/img/gp-initial.png) The blue band enveloping the regressor represents the standard deviation of the Gaussian process at the given point. Now we are ready to do active learning! ```python # active learning n_queries = 10 for idx in range(n_queries): query_idx, query_instance = regressor.query(X) regressor.teach(X[query_idx].reshape(1, -1), y[query_idx].reshape(1, -1)) ``` After a few queries, we can see that the prediction is much improved. ![gp-final](https://cosmic-cortex.github.io/modAL/img/gp-final.png) ## Additional examples<a name="additional-examples"></a> Including this, many examples are available: - [Pool-based sampling](https://cosmic-cortex.github.io/modAL/Pool-based-sampling) - [Stream-based sampling](https://cosmic-cortex.github.io/modAL/Stream-based-sampling) - [Active regression](https://cosmic-cortex.github.io/modAL/Active-regression) - [Ensemble regression](https://cosmic-cortex.github.io/modAL/Ensemble-regression) - [Query by committee](https://cosmic-cortex.github.io/modAL/Query-by-committee) - [Bootstrapping and bagging](https://cosmic-cortex.github.io/modAL/Bootstrapping-and-bagging) - [Keras integration](https://cosmic-cortex.github.io/modAL/Keras-integration) # Installation<a name="installation"></a> modAL requires - Python >= 3.5 - NumPy >= 1.13 - SciPy >= 0.18 - scikit-learn >= 0.18 You can install modAL directly with pip: ``` pip install modAL ``` Alternatively, you can install modAL directly from source: ``` pip install git+https://github.com/cosmic-cortex/modAL.git ``` For running the examples, Matplotlib >= 2.0 is recommended. # About the developer<a name="about-the-developer"> modAL is developed by me, [Tivadar Danka](https://www.tivadardanka.com) (aka [cosmic-cortex](https://github.com/cosmic-cortex) in GitHub). I have a PhD in pure mathematics, but I fell in love with biology and machine learning right after I finished my PhD. I have changed fields and now I work in the [Bioimage Analysis and Machine Learning Group of Peter Horvath](http://group.szbk.u-szeged.hu/sysbiol/horvath-peter-lab-index.html), where I am working to develop active learning strategies for intelligent sample analysis in biology. During my work I realized that in Python, creating and prototyping active learning workflows can be made really easy and fast with scikit-learn, so I ended up developing a general framework for this. The result is modAL :) If you have any questions, requests or suggestions, you can contact me at <a href="mailto:85a5187a@opayq.com">85a5187a@opayq.com</a>! I hope you'll find modAL useful! Anyone who agrees with this pull request could vote for it by adding a :+1: to it, and usually, the maintainer will merge it when votes reach **20**. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2025-11-06 13:05:15 -06:00

GiteaMirror closed this issue

2025-11-06 13:05:15 -06:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/awesome-python#913