Importing tree ensemble models
==============================

Since the scope of Treelite is limited to **prediction** only, one must use
other machine learning packages to **train** decision tree ensemble models. In
this document, we will show how to import an ensemble model that had been
trained elsewhere.

.. contents:: Contents
  :local:
  :backlinks: none

Importing XGBoost models
------------------------

**XGBoost** (`dmlc/xgboost <https://github.com/dmlc/xgboost/>`_) is a fast,
scalable package for gradient boosting. Both Treelite and XGBoost are hosted
by the DMLC (Distributed Machine Learning Community) group.

Treelite plays well with XGBoost --- if you used XGBoost to train your ensemble
model, you need only one line of code to import it. Depending on where your
model is located, you should do one of the following:

* Load XGBoost model from a :py:class:`xgboost.Booster` object

.. code-block:: python

  # bst = an object of type xgboost.Booster
  model = Model.from_xgboost(bst)

* Load XGBoost model from a binary model file

.. code-block:: python

  # model had been saved to a file named my_model.model
  # notice the second argument model_format='xgboost'
  model = Model.load('my_model.model', model_format='xgboost')

Importing LightGBM models
-------------------------

**LightGBM** (`Microsoft/LightGBM <https://github.com/Microsoft/LightGBM>`_) is
another well known machine learning package for gradient boosting. To import
models generated by LightGBM, use the :py:meth:`~treelite.Model.load` method
with argument ``model_format='lightgbm'``:

.. code-block:: python

  # model had been saved to a file named my_model.txt
  # notice the second argument model_format='lightgbm'
  model = Model.load('my_model.txt', model_format='lightgbm')

Importing scikit-learn models
-----------------------------
**Scikit-learn** (`scikit-learn/scikit-learn
<https://github.com/scikit-learn/scikit-learn>`_) is a Python machine learning
package known for its versatility and ease of use. It supports a wide variety
of models and algorithms. The following kinds of models can be imported into
Treelite.

* :py:class:`sklearn.ensemble.RandomForestRegressor`
* :py:class:`sklearn.ensemble.RandomForestClassifier`
* :py:class:`sklearn.ensemble.GradientBoostingRegressor`
* :py:class:`sklearn.ensemble.GradientBoostingClassifier`

To import scikit-learn models, use
:py:meth:`treelite.sklearn.import_model`:

.. code-block:: python

  # clf is the model object generated by scikit-learn
  import treelite.sklearn
  model = treelite.sklearn.import_model(clf)

How about other packages?
-------------------------
If you used other packages to train your ensemble model, you'd need to specify
the model programmatically:

* :doc:`builder`