tf.estimator.RegressionHead

TensorFlow 1 version View source on GitHub

Creates a Head for regression using the mean_squared_error loss.

Inherits From: Head

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, loss_reduction) 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.

Usage:

head = tf.estimator.RegressionHead()
logits = np.array(((45,), (41,),), dtype=np.float32)
labels = np.array(((43,), (44,),), dtype=np.int32)
features = {'x': np.array(((42,),), dtype=np.float32)}
# expected_loss = weighted_loss / batch_size
#               = (43-45)^2 + (44-41)^2 / 2 = 6.50
loss = head.loss(labels, logits, features=features)
print('{:.2f}'.format(loss.numpy()))
6.50
eval_metrics = head.metrics()
updated_metrics = head.update_metrics(
  eval_metrics, features, logits, labels)
for k in sorted(updated_metrics):
 print('{} : {:.2f}'.format(k, updated_metrics[k].result().numpy()))
  average_loss : 6.50
  label/mean : 43.50
  prediction/mean : 43.00
preds = head.predictions(logits)
print(preds['predictions'])
tf.Tensor(
  [[45.]
   [41.]], shape=(2, 1), dtype=float32)

Usage with a canned estimator:

my_head = tf.estimator.RegressionHead()
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.estimator.RegressionHead()
  logits = tf.keras.Model(...)(features)

  return my_head.create_estimator_spec(
      features=features,
      mode=mode,
      labels=labels,
      optimizer=tf.keras.optimizers.Adagrad(lr=0.1),
      logits=logits)

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

weight_column A string or a NumericColumn created by 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 except NONE. Decides 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.
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.

logits_dimension See base_head.Head for details.
loss_reduction See base_head.Head for details.
name See base_head.Head for details.

Methods

create_estimator_spec

View source

Returns EstimatorSpec that a model_fn can return.

It is recommended to pass all args via name.

Args
features Input dict mapping string feature names to Tensor or SparseTensor objects containing the values for that feature in a minibatch. Often to be used to fetch example-weight tensor.
mode Estimator's ModeKeys.
logits Logits Tensor to be used by the head.
labels Labels Tensor, or dict mapping string label names to Tensor objects of the label values.
optimizer An tf.keras.optimizers.Optimizer instance to optimize the loss in TRAIN mode. Namely, sets train_op = optimizer.get_updates(loss, trainable_variables), which updates variables to minimize