MLJAR Automated Machine Learning for Humans

Documentation: https://supervised.mljar.com/

Source Code: https://github.com/mljar/mljar-supervised

Use MLJAR Studio (Easiest Way to Run MLJAR AutoML)
MLJAR Studio is the easiest way to run MLJAR AutoML, with conversational notebooks and AutoLab experiments (autonomous AI for ML pipeline optimization).
Start quickly, iterate faster, and manage experiments in one place.
Try MLJAR Studio

Table of Contents

• Automated Machine Learning
• Generate Web Apps for Trained Models
• What's good in it?
• Automatic Documentation
• Available Modes
• Fairness Aware Training
• Examples
• FAQ
• Documentation
• Installation
• Demo
• Contributing
• Cite
• License
• Commercial support
• MLJAR

Automated Machine Learning

The mljar-supervised is an Automated Machine Learning Python package that works with tabular data. It is designed to save time for a data scientist. It abstracts the common way to preprocess the data, construct the machine learning models, and perform hyper-parameters tuning to find the best model :trophy:. It is no black box, as you can see exactly how the ML pipeline is constructed (with a detailed Markdown report for each ML model).

The mljar-supervised will help you with:

• explaining and understanding your data through model reports, feature importance, and SHAP explanations,
• trying many different machine learning models (Algorithm Selection and Hyper-Parameters tuning),
• creating Markdown reports from analysis with details about all models (Automatic-Documentation),
• generating a web app for a trained model, so predictions can be used by domain experts,
• saving, re-running, and loading the analysis and ML models.

It has four built-in modes of work:

• Explain mode, which is ideal for explaining and understanding the data, with many data explanations, like decision trees visualization, linear models coefficients display, permutation importance, and SHAP explanations of data,
• Perform for building ML pipelines to use in production,
• Compete mode that trains highly-tuned ML models with ensembling and stacking, with the purpose to use in ML competitions.
• Optuna mode can be used to search for highly-tuned ML models should be used when the performance is the most important, and computation time is not limited (it is available from version 0.10.0)

Of course, you can further customize the details of each mode to meet the requirements.

Generate Web Apps for Trained Models

MLJAR AutoML does not stop after training a model. It can automatically generate a web app for your trained model with Mercury. This is useful when you want to share predictions with domain experts, business users, researchers, or other people who do not want to work directly with Python code.

After training AutoML, generate the app files with:

from supervised import AutoML
# AutoML training
automl = AutoML(results_path="AutoML")
automl.fit(X, y)

# Generate a Mercury web app for the trained model
automl.app()

You can also start the app locally:

automl.local_app()

or publish it quickly:

automl.publish_app()

publish_app() creates an app URL on the first publish and then reuses the last successfully published URL by default.

The generated app can include:

• single prediction dashboard,
• batch prediction from CSV files,
• downloadable predictions,
• feature importance plots,
• feature context plots for single predictions.

With this feature, you can go from: CSV data -> trained ML model -> ready-to-use prediction web app.

Please check the Apps documentation for details.

What's good in it?

• It uses many algorithms: Baseline, Linear, Random Forest, Extra Trees, LightGBM, Xgboost, CatBoost, Neural Networks, and Nearest Neighbors.
• It can compute Ensemble based on a greedy algorithm from Caruana paper.
• It can stack models to build a level 2 ensemble (available in Compete mode or after setting the stack_models parameter).
• It can do features preprocessing, like missing values imputation and converting categoricals. What is more, it can also handle target values preprocessing.
• It can do advanced features engineering, like Golden Features, Features Selection, Text and Time Transformations.
• It can tune hyper-parameters with a not-so-random-search algorithm (random-search over a defined set of values) and hill climbing to fine-tune final models.
• It can compute the Baseline for your data so that you will know if you need Machine Learning or not!
• It has extensive explanations. This package is training simple Decision Trees with max_depth <= 5, so you can easily visualize them with amazing dtreeviz to better understand your data.
• The mljar-supervised uses simple linear regression and includes its coefficients in the summary report, so you can check which features are used the most in the linear model.
• It cares about the explainability of models: for every algorithm, the feature importance is computed based on permutation. Additionally, for every algorithm, the SHAP explanations are computed: feature importance, dependence plots, and decision plots (explanations can be switched off with the explain_level parameter).
• There is automatic documentation for every ML experiment run with AutoML. The mljar-supervised creates markdown reports from AutoML training full of ML details, metrics, and charts.
• It can generate Mercury web apps from trained AutoML models, so the model can be shared as an interactive prediction app.

Automatic Documentation

The AutoML Report

The report from running AutoML will contain the table with information about each model score and the time needed to train the model. There is a link for each model, which you can click to see the model's details. The performance of all ML models is presented as scatter and box plots so you can visually inspect which algorithms perform the best :trophy:.

The Decision Tree Report

The example for Decision Tree summary with trees visualization. For classification tasks, additional metrics are provided:

• confusion matrix
• threshold (optimized in the case of binary classification task)
• F1 score
• Accuracy
• Precision, Recall, MCC

The LightGBM Report

The example for LightGBM summary:

Available Modes

In the docs you can find details about AutoML modes that are presented in the table.

Explain

automl = AutoML(mode="Explain")

It is aimed to be used when the user wants to explain and understand the data.

• It is using 75%/25% train/test split.
• It uses: Baseline, Linear, Decision Tree, Random Forest, Xgboost, `Neural Network' algorithms, and ensemble.
• It has full explanations: learning curves, importance plots, and SHAP plots.

Perform

automl = AutoML(mode="Perform")

It should be used when the user wants to train a model that will be used in real-life use cases.

• It uses a 5-fold CV.
• It uses: Linear, Random Forest, LightGBM, Xgboost, CatBoost, and Neural Network. It uses ensembling.
• It has learning curves and importance plots in reports.

Compete

automl = AutoML(mode="Compete")

It should be used for machine learning competitions.

• It adapts the validation strategy depending on dataset size and total_time_limit. It can be: a train/test split (80/20), 5-fold CV or 10-fold CV.
• It is using: Linear, Decision Tree, Random Forest, Extra Trees, LightGBM, Xgboost, CatBoost, Neural Network, and Nearest Neighbors. It uses ensemble and stacking.
• It has only learning curves in the reports.

Optuna

automl = AutoML(mode="Optuna", optuna_time_budget=3600)

It should be used when the performance is the most important and time is not limited.

• It uses a 10-fold CV
• It uses: Random Forest, Extra Trees, LightGBM, Xgboost, and CatBoost. Those algorithms are tuned by Optuna framework for optuna_time_budget seconds, each. Algorithms are tuned with original data, without advanced feature engineering.
• It uses advanced feature engineering, stacking and ensembling. The hyperparameters found for original data are reused with those steps.
• It produces learning curves in the reports.

How to save and load AutoML?

All models in the AutoML are saved and loaded automatically. No need to call save() or load().

Example:

Train AutoML

automl = AutoML(results_path="AutoML_classifier")
automl.fit(X, y)

You will have all models saved in the AutoML_classifier directory. Each model will have a separate directory with the README.md file with all details from the training.

Compute predictions

automl = AutoML(results_path="AutoML_classifier")
automl.predict(X)

The AutoML automatically loads models from the results_path directory. If you will call fit() on already trained AutoML then you will get a warning message that AutoML is already fitted.

Why do you automatically save all models?

All models are automatically saved to be able to restore the training after interruption. For example, you are training AutoML for 48 hours, and after 47 hours, there is some unexpected interruption. In MLJAR AutoML you just call the same training code after the interruption and AutoML reloads already trained models and finishes the training.

Supported evaluation metrics (eval_metric argument in AutoML())

• for binary classification: logloss, auc, f1, average_precision, accuracy- default is logloss
• for multiclass classification: logloss, f1, accuracy - default is logloss
• for regression: rmse, mse, mae, r2, mape, spearman, pearson - default is rmse

You can also pass a custom Python function directly as eval_metric. See the docs for Custom eval metric.

If you don't find the eval_metric that you need, please add a new issue. We will add it.

Fairness Aware Training

Starting from version 1.0.0 AutoML can optimize the Machine Learning pipeline with sensitive features. There are the following fairness related arguments in the AutoML constructor:

• fairness_metric - metric which will be used to decide if the model is fair,
• fairness_threshold - threshold used in decision about model fairness,
• privileged_groups - privileged groups used in fairness metrics computation,
• underprivileged_groups - underprivileged groups used in fairness metrics computation.

The fit() method accepts sensitive_features. When sensitive features are passed to AutoML, the best model will be selected among fair models only. In the AutoML reports, additional information about fairness metrics will be added. The MLJAR AutoML supports two methods for bias mitigation:

• Sample Weighting - assigns weights to samples to treat samples equally,
• Smart Grid Search - similar to Sample Weighting, where different weights are checked to optimize fairness metric.

The fair ML building can be used with all algorithms, including Ensemble and Stacked Ensemble. We support three Machine Learning tasks:

• binary classification,
• mutliclass classification,
• regression.

Example code:

from sklearn.model_selection import train_test_split
from sklearn.datasets import fetch_openml
from supervised.automl import AutoML

data = fetch_openml(data_id=1590, as_frame=True)
X = data.data
y = (data.target == ">50K") * 1
sensitive_features = X[["sex"]]

X_train, X_test, y_train, y_test, S_train, S_test = train_test_split(
    X, y, sensitive_features, stratify=y, test_size=0.75, random_state=42
)

automl = AutoML(
    algorithms=[
        "Xgboost"
    ],
    train_ensemble=False,
    fairness_metric="demographic_parity_ratio",  
    fairness_threshold=0.8,
    privileged_groups = [{"sex": "Male"}],
    underprivileged_groups = [{"sex": "Female"}],
)

automl.fit(X_train, y_train, sensitive_features=S_train)

You can read more about fairness aware AutoML training in our article https://mljar.com/blog/fairness-machine-learning/

Examples

:point_right: Binary Classification Example

There is a simple interface available with fit and predict methods.

import pandas as pd
from sklearn.model_selection import train_test_split
from supervised.automl import AutoML

df = pd.read_csv(
    "https://raw.githubusercontent.com/pplonski/datasets-for-start/master/adult/data.csv",
    skipinitialspace=True,
)
X_train, X_test, y_train, y_test = train_test_split(
    df[df.columns[:-1]], df["income"], test_size=0.25
)

automl = AutoML()
automl.fit(X_train, y_train)

predictions = automl.predict(X_test)

AutoML fit will print:

Create directory AutoML_1
AutoML task to be solved: binary_classification
AutoML will use algorithms: ['Baseline', 'Linear', 'Decision Tree', 'Random Forest', 'Xgboost', 'Neural Network']
AutoML will optimize for metric: logloss
1_Baseline final logloss 0.5519845471086654 time 0.08 seconds
2_DecisionTree final logloss 0.3655910192804364 time 10.28 seconds
3_Linear final logloss 0.38139916864708445 time 3.19 seconds
4_Default_RandomForest final logloss 0.2975204390214936 time 79.19 seconds
5_Default_Xgboost final logloss 0.2731086827200411 time 5.17 seconds
6_Default_NeuralNetwork final logloss 0.319812276905242 time 21.19 seconds
Ensemble final logloss 0.2731086821194617 time 1.43 seconds

• the AutoML results in Markdown report
• the Xgboost Markdown report, please take a look at amazing dependence plots produced by SHAP package :sparkling_heart:
• the Decision Tree Markdown report, please take a look at beautiful tree visualization :sparkles:
• the Logistic Regression Markdown report, please take a look at coefficients table, and you can compare the SHAP plots between (Xgboost, Decision Tree and Logistic Regression) :coffee:

:point_right: Multi-Class Classification Example

The example code for classification of the optical recognition of handwritten digits dataset. Running this code in less than 30 minutes will result in test accuracy ~98%.

import pandas as pd 
# scikit learn utilites
from sklearn.datasets import load_digits
from sklearn.metrics import accuracy_score
from sklearn.model_selection import train_test_split
# mljar-supervised package
from supervised.automl import AutoML

# load the data
digits = load_digits()
X_train, X_test, y_train, y_test = train_test_split(
    pd.DataFrame(digits.data), digits.target, stratify=digits.target, test_size=0.25,
    random_state=123
)

# train models with AutoML
automl = AutoML(mode="Perform")
automl.fit(X_train, y_train)

# compute the accuracy on test data
predictions = automl.predict_all(X_test)
print(predictions.head())
print("Test accuracy:", accuracy_score(y_test, predictions["label"].astype(int)))

:point_right: Regression Example

Regression example on California Housing house prices data.

import numpy as np
import pandas as pd
from sklearn.datasets import fetch_california_housing
from sklearn.model_selection import train_test_split
from sklearn.metrics import mean_squared_error
from supervised.automl import AutoML # mljar-supervised

# Load the data
housing = fetch_california_housing()
X_train, X_test, y_train, y_test = train_test_split(
    pd.DataFrame(housing.data, columns=housing.feature_names),
    housing.target,
    test_size=0.25,
    random_state=123,
)

# train models with AutoML
automl = AutoML(mode="Explain")
automl.fit(X_train, y_train)

# compute the MSE on test data
predictions = automl.predict(X_test)
print("Test MSE:", mean_squared_error(y_test, predictions))

:point_right: More Examples

• Income classification - it is a binary classification task on census data
• Iris classification - it is a multiclass classification on Iris flowers data
• House price regression - it is a regression task on Boston houses data

FAQ

automl = AutoML(results_path='AutoML_1')
automl.fit(X, y)

automl = AutoML(results_path='AutoML_1')
automl.predict(X)

automl = AutoML(ml_task='regression')
automl.fit(X, y)

optuna_init = json.loads(open('previous_AutoML_training/optuna/optuna.json').read())

automl = AutoML(
    mode='Optuna',
    optuna_init_params=optuna_init
)
automl.fit(X, y)

Documentation

For details please check mljar-supervised docs.

Structured Report for LLMs

The AutoML object can generate a structured report that is easier to analyze with LLMs and external tools:

from supervised import AutoML

automl = AutoML(results_path="AutoML_example")
automl.fit(X, y)

# Default output is markdown text
markdown_report = automl.report_structured()
print(markdown_report)

You can also get programmatic formats:

# Python dictionary
payload = automl.report_structured(format="dict")

# JSON string
payload_json = automl.report_structured(format="json")

Each call creates/updates:

<results_path>/report_structured.json

Use model_name to display detailed metrics for one selected model:

compact = automl.report_structured()
detailed = automl.report_structured(model_name="3_Linear")

When model_name is provided, the markdown includes detailed metrics, fairness details (if used), and feature importance summaries for that model.

Installation

Compatibility:

• Python >=3.9
• NumPy >=2.0,<3

From PyPi repository:

pip install mljar-supervised

To install this package with conda run:

conda install -c conda-forge mljar-supervised

From source code:

git clone https://github.com/mljar/mljar-supervised.git
cd mljar-supervised
python setup.py install

Installation for development

git clone https://github.com/mljar/mljar-supervised.git
virtualenv venv --python=python3.9
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements_dev.txt

Running in the docker:

FROM python:3.9-slim-buster
RUN apt-get update && apt-get -y update
RUN apt-get install -y build-essential python3-pip python3-dev
RUN pip3 -q install pip --upgrade
RUN pip3 install mljar-supervised jupyter
CMD ["jupyter", "notebook", "--port=8888", "--no-browser", "--ip=0.0.0.0", "--allow-root"]

Install from GitHub with pip:

pip install -q -U git+https://github.com/mljar/mljar-supervised.git@master

Demo

In the below demo GIF you will see:

• MLJAR AutoML trained in Jupyter Notebook on the Titanic dataset
• overview of created files
• a showcase of selected plots created during AutoML training
• algorithm comparison report along with their plots
• example of README file and CSV file with results

Contributing

To get started take a look at our Contribution Guide for information about our process and where you can fit in!

Contributors

Cite

Would you like to cite MLJAR? Great! :)

You can cite MLJAR as follows:

@misc{mljar,
  author    = {Aleksandra P\l{}o\'{n}ska and Piotr P\l{}o\'{n}ski},
  year      = {2021},
  publisher = {MLJAR},
  address   = {\L{}apy, Poland},
  title     = {MLJAR: State-of-the-art Automated Machine Learning Framework for Tabular Data.  Version 0.10.3},
  url       = {https://github.com/mljar/mljar-supervised}
}

Would love to hear from you about how have you used MLJAR AutoML in your project. Please feel free to let us know at

License

The mljar-supervised is provided with MIT license.

Commercial support

Looking for commercial support? Do you need new feature implementation? Please contact us by email for details.

MLJAR

The mljar-supervised is an open-source project created by MLJAR. We care about ease of use in Machine Learning. The mljar.com provides a beautiful and simple user interface for building machine learning models.