# tf.contrib.estimator.logistic_regression_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 logistic regression.

    tf.contrib.estimator.logistic_regression_head(
        weight_column=None, loss_reduction=losses.Reduction.SUM_OVER_BATCH_SIZE,
        name=None
    )

Uses `sigmoid_cross_entropy_with_logits` loss, which is the same as
`binary_classification_head`. The differences compared to
`binary_classification_head` are:

- Does not support `label_vocabulary`. Instead, labels must be float in the range \[0, 1\].
- Does not calculate some metrics that do not make sense, such as AUC.
- In `PREDICT` mode, only returns logits and predictions (`=tf.sigmoid(logits)`), whereas `binary_classification_head` also returns probabilities, classes, and class_ids.
- Export output defaults to `RegressionOutput`, whereas `binary_classification_head` defaults to `PredictOutput`.

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

The `labels` shape must match `logits`, namely
`[D0, D1, ... DN]` or `[D0, D1, ... DN, 1]`.

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

This is implemented as a generalized linear model, see
<https://en.wikipedia.org/wiki/Generalized_linear_model>

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

    my_head = tf.contrib.estimator.logistic_regression_head()
    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.logistic_regression_head()
      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 ||
|---|---|
| `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. |
| `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 and label dimension. Defaults to `SUM_OVER_BATCH_SIZE`, namely weighted sum of losses divided by `batch size * label_dimension`. See `tf.losses.Reduction`. |
| `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 logistic regression. ||

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `ValueError` | If `loss_reduction` is invalid. |

<br />