=============
 Model
=============

Model implements the easiest to use interface into our framework and
uses :class:`~autonlu.SimpleModel` internally for training, inference,
etc. Currently, three different text classification tasks and two
sequence labeling tasks are supported.

Text classification
===================

:Label: Exactly one label from a set of possible labels is assigned to
   each segment of text. For example, this might be used for detecting
   sentiment where each sentence either has a sentiment (e.g.
   ``negative``, ``neutral``, or ``positive``) or not, indicated by
   the class ``none``. You have this task, if the training target is a
   **list of strings**. E.g. ``["A", "B", "A"]``
:Class: An arbitrary number of classes (from none to all possible
   classes) is assigned to each segment of text. For example, this
   might be used for topic detection, where each sentence can have
   none or multiple topics. You have this task, if the training target
   is a **list of lists of strings** E.g. ``[["A", "B"], [], ["A"]]``
:Class Label: An arbitrary number of classes (from none to all
   possible classes ) is assigned to each segment of text and each
   detected class is assigned exactly one label from a set of possible
   labels. For example, this can be used for aspect based sentiment
   detection where each sentence can have multiple topics/aspects and
   each of them has a sentiment. You have this task, if the training
   target is a **list of lists of pairs of strings**. E.g. ``[[["A",
   "1"], ["B", "1"]], [], [["A", "2"]]]``

Sequence labeling
=============

:token_classification: Each word in a given text can have its own
   label, e.g. ``person``, ``location``, ``organization``, etc.
   Training samples are provided in the form of simple **markup
   language** texts.
:question_answering: Samples consist of ``question``-``context``-
   tuples. The model searches for words in the ``context`` which
   qualify as answer to the ``question``. For training, the
   ``context`` is provided in a **markup language**, where the correct
   words are tagged.

Every trained model that can be loaded has (implicitly) one of these
tasks associated with it. For *text classification*, the specific task
is automatically deduced from the data. More precisely, it depends on
whether a list of all classes is given and how the list of labels
looks like in the ``meta.json`` file in the model folder.
As a user, you do not have to concern yourself with this.
For the *sequence labeling* tasks, it suffice to instantiate the model
with the argument **task="token_classification"** or
**task="question_answering"**.

This makes for a very easy to use interface to our whole system and
many tasks can be solved with < 5 lines of code.

Model types
===========
Currently, three different model types are supported by AutoNLU:

:Standard Models: Support all tasks and are the main model to be used
                  for label tasks and sequence labeling tasks. A
                  standard model is used if no postfix is attached to
                  a base model name. E.g.
                  ``Model("bert-base-uncased")`` would create a
                  standard model. We recommend this model for label
                  tasks.

:OMI Models: Is a newly introduced type of model which is highly
   effective for class and classlabel tasks. For these tasks it
   generally trains and predicts much faster and achieves slightly
   higher accuracies that standard models. You are using this kind of
   model type if you append ``#omi`` to any base model name (e.g.
   ``Model("bert-base-uncased#omi")``). OMI models do not support, and
   are not useful for, label tasks. They have some additional
   disadvantages. For example, standard models generalize to unseen
   classes to a certain degree (i.e. they can be used to predict
   classes they were not seen on previously). This is not possible for
   OMI. We recommend this model in most cases for class as well as
   classlabel tasks.

:CNN Models: Is a highly efficient model type which supports all three
   tasks. It can be more than 10 times faster than even an OMI model
   for prediction. You are using this kind of model type if you append
   ``#cnn`` to any base model name (e.g.
   ``Model("albert-base-v2#cnn")``). The base model here mainly
   specifies which embeddings will be used for the tokens. We
   recommend using ``albert-base-v2`` in most cases. The speed comes
   at a price and CNN models usually achieve slightly lower accuracies
   than the two other types of models. In addition, some functionality
   is not currently supported for CNN models (e.g.
   :func:`autonlu.Model.finetune`,
   :func:`autonlu.Model.select_to_label`) We recommend CNN models if
   prediction speed is very important and as a student model target
   for distillation.

The Model Class
===============

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. autoclass:: autonlu.Model
   :members: predict, train, save, finetune, select_to_label, modeltype, evaluate, upload, prune, auto_prune, distill