# tf.contrib.estimator.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 regression using the `mean_squared_error` loss.

    tf.contrib.estimator.regression_head(
        weight_column=None, label_dimension=1,
        loss_reduction=losses.Reduction.SUM_OVER_BATCH_SIZE, loss_fn=None,
        inverse_link_fn=None, name=None
    )

The loss is the weighted sum over all input dimensions. Namely, if the input
labels have shape `[batch_size, label_dimension]`, the loss is the weighted
sum over both `batch_size` and `label_dimension`.

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

The `labels` shape must match `logits`, namely
`[D0, D1, ... DN, label_dimension]`. If `label_dimension=1`, shape
`[D0, D1, ... DN]` is also supported.

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

Supports custom `loss_fn`. `loss_fn` takes `(labels, logits)` or
`(labels, logits, features)` as arguments and returns unreduced loss with
shape `[D0, D1, ... DN, label_dimension]`.

Also supports custom `inverse_link_fn`, also known as 'mean function'.
`inverse_link_fn` is only used in `PREDICT` mode. It takes `logits` as
argument and returns predicted values. This function is the inverse of the
link function defined in
<https://en.wikipedia.org/wiki/Generalized_linear_model#Link_function>
Namely, for poisson regression, set `inverse_link_fn=tf.exp`.

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

    my_head = tf.contrib.estimator.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.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. |
| `label_dimension` | Number of regression labels per example. This is the size of the last dimension of the labels `Tensor` (typically, this has shape `[batch_size, label_dimension]`). |
| `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`. |
| `loss_fn` | Optional loss function. Defaults to `mean_squared_error`. |
| `inverse_link_fn` | Optional inverse link function, also known as 'mean function'. Defaults to identity. |
| `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 linear regression. ||

<br />

<br />

<br />

<br />

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

<br />