###########
coremltools
###########

.. _about:

**Core ML** is an Apple framework that allows developers to easily integrate
machine learning (ML) models into apps. Core ML is available on iOS, iPadOS,
watchOS, macOS, and tvOS. Core ML introduces a public file format (.mlmodel)
for a broad set of ML methods including deep neural networks (convolutional
and recurrent), tree ensembles (boosted trees, random forest, decision trees),
and generalized linear models. Core ML models can be directly integrated into
apps within Xcode.

**coremltools** is a Python package that can be used to:

- Convert trained models from popular machine learning tools into Core ML format
  (.mlmodel).
- Write models to Core ML format with a simple API.
- Making predictions using the Core ML framework (on select platforms) to
  verify conversion.

.. currentmodule:: coremltools

Installation
------------

**coremltools** has the following dependencies:

- numpy (1.12.1+)

- protobuf (3.1.0+)

In addition, it has the following soft dependencies that are only needed when
you are converting models of these formats:

- Keras (1.2.2, 2.0.4+) with TensorFlow (1.0+)

- XGBoost (0.6+)

- scikit-learn (0.15+)

- LIBSVM

The method for installing **coremltools** follows the
`standard python package installation steps <https://packaging.python.org/installing/>`_.
Once you have set up a python environment, run::

    pip install --upgrade coremltools

to install **coremltools**.

Model Conversion
================

**coremltools** easily converts trained models from existing libraries. The
following example shows how to convert a Caffe model (`AlexNet
<http://dl.caffe.berkeleyvision.org/bvlc_alexnet.caffemodel>`_) to Core ML
format (.mlmodel).

Supporting files: `bvlc_alexnet.caffemodel <http://dl.caffe.berkeleyvision.org/bvlc_alexnet.caffemodel>`_, `deploy.prototxt <https://raw.githubusercontent.com/BVLC/caffe/master/models/bvlc_alexnet/deploy.prototxt>`_, `class_labels.txt <https://raw.githubusercontent.com/torch/tutorials/master/7_imagenet_classification/synset_words.txt>`_.

.. code-block:: python

    import coremltools

    # Convert a Caffe model to a classifier in Core ML
    coreml_model = coremltools.converters.caffe.convert(
        ('bvlc_alexnet.caffemodel', 'deploy.prototxt'), predicted_feature_name='class_labels.txt'
    )

    # Now save the model
    coreml_model.save('BVLCObjectClassifier.mlmodel')

Here is another example with scikit-learn:

.. code-block:: python

    from sklearn.linear_model import LinearRegression
    import pandas as pd

    # Load data
    data = pd.read_csv('houses.csv')

    # Train a model
    model = LinearRegression()
    model.fit(data[["bedroom", "bath", "size"]], data["price"])

    # Convert and save the scikit-learn model
    import coremltools

    coreml_model = coremltools.converters.sklearn.convert(model, ["bedroom", "bath", "size"], "price")

Model Interface
===============

After conversion, you might want to edit the model metadata to make your model
easier to consume in Xcode. The license, author, and other metadata get
surfaced in the Xcode UI while the input and output descriptions are surfaced
as comments in the code generated by Xcode for the model consumer.

.. code-block:: python

    # Set model metadata
    model.author = 'John Smith'
    model.license = 'BSD'
    model.short_description = 'Predicts the price of a house in the Seattle area.'

    # Set feature descriptions manually
    model.input_description['bedroom'] = 'Number of bedrooms'
    model.input_description['bathrooms'] = 'Number of bathrooms'
    model.input_description['size'] = 'Size (in square feet)'

    # Set the output descriptions
    model.output_description['price'] = 'Price of the house'

    # Save the model
    model.save('HousePricer.mlmodel')

Model Evaluation
================

After conversion, you might want to verify that the predictions made by Core ML
match up with the source framework. To facilitate programmatic verification of
the conversion, we provide a way for you to easily evaluate Core ML models.

Here is an example using making predictions using the :code:`HousePricer.mlmodel`
that we converted in the previous example:

.. code-block:: python

    import coremltools

    # Load the model
    model = coremltools.models.MLModel('HousePricer.mlmodel')

    # Make predictions
    predictions = model.predict({'bedroom': 1.0, 'bath': 1.0, 'size': 1240})

Conversion Support
==================

Core ML supports conversion of trained models from a variety of training tools
for integration into apps. The following table lists supported tool packages
by model type:

+---------------------------+--------------------------------------+
| Model Family              | Supported Packages                   |
+===========================+======================================+
| Neural Networks           | Keras (1.2.2, 2.0.4+), Caffe (1.0)   |
+---------------------------+--------------------------------------+
| Tree Ensembles            | XGBoost (0.6), scikit-learn (0.18.1) |
+---------------------------+--------------------------------------+
| Generalized Linear Models | scikit-learn (0.18.1)                |
+---------------------------+--------------------------------------+
| Support Vector Machines   | LIBSVM (3.22), scikit-learn (0.18.1) |
+---------------------------+--------------------------------------+
| Feature Engineering       | scikit-learn (0.18.1)                |
+---------------------------+--------------------------------------+
| Pipelines                 | scikit-learn (0.18.1)                |
+---------------------------+--------------------------------------+

Model Visualization
===================

Core ML supports visualizing a converted model. This can be used to see all
the building blocks of the model.

Here is an example of visualizing the :code:`HousePricer.mlmodel`:

.. code-block:: python

    import coremltools

    # Load the model
    model = coremltools.models.MLModel('HousePricer.mlmodel')

    # Visualize the model
    model.visualize_spec()

Model Specification
===================

A key component of Core ML is the public specification for representing machine
learning models. This specification is defined in `protobuf <https://developers.google.com/protocol-buffers/>`_ and can be created
using any language supported by protobuf (e.g., Python, C++, Java, C#, Perl, etc.).

At a high level, the protobuf specification consists of:

- Model description: Encodes names and type information of the inputs and outputs to the model.
- Model parameters: The set of parameters required to represent a specific instance of the model.
- Metadata: Information about the origin, license, and author of the model.

For more information, please take a look at the `Core ML model specification <https://apple.github.io/coremltools/coremlspecification>`_.

External Tools
==============
In addition to the conversion tools in this package, TensorFlow, MXNet and ONNX have their own conversion tools:

- `TensorFlow <https://pypi.python.org/pypi/tfcoreml>`_
- `MXNet <https://github.com/apache/incubator-mxnet/tree/master/tools/coreml>`_
- `ONNX <https://github.com/onnx/onnx-coreml>`_

Contents
========

.. toctree::
    :maxdepth: 1

    coremltools.converters.rst
    coremltools.models.rst
    coremltools.utils.rst