# tf.contrib.estimator.multi_label_head

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/estimator/tree/master/tensorflow_estimator/contrib/estimator/python/estimator/head.py) |

Creates a `_Head` for multi-label classification.

    tf.contrib.estimator.multi_label_head(
        n_classes, weight_column=None, thresholds=None, label_vocabulary=None,
        loss_reduction=losses.Reduction.SUM_OVER_BATCH_SIZE, loss_fn=None,
        classes_for_class_based_metrics=None, name=None
    )

Multi-label classification handles the case where each example may have zero
or more associated labels, from a discrete set. This is distinct from
`multi_class_head` which has exactly one label per example.

Uses `sigmoid_cross_entropy` loss average over classes and weighted sum over
the batch. Namely, if the input logits have shape `[batch_size, n_classes]`,
the loss is the average over `n_classes` and the weighted sum over
`batch_size`.

The head expects `logits` with shape `[D0, D1, ... DN, n_classes]`. In many
applications, the shape is `[batch_size, n_classes]`.

#### Labels can be:

- A multi-hot tensor of shape `[D0, D1, ... DN, n_classes]`
- An integer `SparseTensor` of class indices. The `dense_shape` must be `[D0, D1, ... DN, ?]` and the values within `[0, n_classes)`.
- If `label_vocabulary` is given, a string `SparseTensor`. The `dense_shape` must be `[D0, D1, ... DN, ?]` and the values within `label_vocabulary` or a multi-hot tensor of shape `[D0, D1, ... DN, n_classes]`.

If `weight_column` is specified, weights must be of shape
`[D0, D1, ... DN]`, or `[D0, D1, ... DN, 1]`.

Also supports custom `loss_fn`. `loss_fn` takes `(labels, logits)` or
`(labels, logits, features)` as arguments and returns unreduced loss with
shape `[D0, D1, ... DN, 1]`. `loss_fn` must support indicator `labels` with
shape `[D0, D1, ... DN, n_classes]`. Namely, the head applies
`label_vocabulary` to the input labels before passing them to `loss_fn`.

The head can be used with a canned estimator. Example:

    my_head = tf.contrib.estimator.multi_label_head(n_classes=3)
    my_estimator = tf.estimator.DNNEstimator(
        head=my_head,
        hidden_units=...,
        feature_columns=...)

It can also be used with a custom `model_fn`. Example:

    def _my_model_fn(features, labels, mode):
      my_head = tf.contrib.estimator.multi_label_head(n_classes=3)
      logits = tf.keras.Model(...)(features)

      return my_head.create_estimator_spec(
          features=features,
          mode=mode,
          labels=labels,
          optimizer=tf.AdagradOptimizer(learning_rate=0.1),
          logits=logits)

    my_estimator = tf.estimator.Estimator(model_fn=_my_model_fn)

<br />

<br />

<br />

| ## Args ||
|---|---|
| `n_classes` | Number of classes, must be greater than 1 (for 1 class, use `binary_classification_head`). |
| `weight_column` | A string or a `_NumericColumn` created by [`tf.feature_column.numeric_column`](https://www.tensorflow.org/versions/r1.15/api_docs/python/tf/feature_column/numeric_column) defining feature column representing weights. It is used to down weight or boost examples during training. It will be multiplied by the loss of the example. Per-class weighting is not supported. |
| `thresholds` | Iterable of floats in the range `(0, 1)`. Accuracy, precision and recall metrics are evaluated for each threshold value. The threshold is applied to the predicted probabilities, i.e. above the threshold is `true`, below is `false`. |
| `label_vocabulary` | A list of strings represents possible label values. If it is not given, that means labels are already encoded as integer within \[0, n_classes) or multi-hot Tensor. If given, labels must be SparseTensor string type and have any value in `label_vocabulary`. Also there will be errors if vocabulary is not provided and labels are string. |
| `loss_reduction` | One of [`tf.losses.Reduction`](https://www.tensorflow.org/versions/r1.15/api_docs/python/tf/losses/Reduction) except `NONE`. Describes how to reduce training loss over batch. Defaults to `SUM_OVER_BATCH_SIZE`, namely weighted sum of losses divided by batch size. See [`tf.losses.Reduction`](https://www.tensorflow.org/versions/r1.15/api_docs/python/tf/losses/Reduction). |
| `loss_fn` | Optional loss function. |
| `classes_for_class_based_metrics` | List of integer class IDs or string class names for which per-class metrics are evaluated. If integers, all must be in the range `[0, n_classes - 1]`. If strings, all must be in `label_vocabulary`. |
| `name` | name of the head. If provided, summary and metrics keys will be suffixed by `"/" + name`. Also used as `name_scope` when creating ops. |

<br />

<br />

<br />

<br />

| ## Returns ||
|---|---|
| An instance of `_Head` for multi-label classification. ||

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `ValueError` | if `n_classes`, `thresholds`, `loss_reduction`, `loss_fn` or `metric_class_ids` is invalid. |

<br />