tf.estimator.experimental.RNNEstimator

View source on GitHub

An Estimator for TensorFlow RNN models with user-specified head.

Inherits From: Estimator

tf.estimator.experimental.RNNEstimator(
    head, sequence_feature_columns, context_feature_columns=None, units=None,
    cell_type=USE_DEFAULT, rnn_cell_fn=None, return_sequences=False, model_dir=None,
    optimizer='Adagrad', config=None
)

Example:

token_sequence = sequence_categorical_column_with_hash_bucket(...)
token_emb = embedding_column(categorical_column=token_sequence, ...)

estimator = RNNEstimator(
    head=tf.estimator.RegressionHead(),
    sequence_feature_columns=[token_emb],
    units=[32, 16], cell_type='lstm')

# Or with custom RNN cell:
def rnn_cell_fn(_):
  cells = [ tf.keras.layers.LSTMCell(size) for size in [32, 16] ]
  return tf.keras.layers.StackedRNNCells(cells)

estimator = RNNEstimator(
    head=tf.estimator.RegressionHead(),
    sequence_feature_columns=[token_emb],
    rnn_cell_fn=rnn_cell_fn)

# Input builders
def input_fn_train: # returns x, y
  pass
estimator.train(input_fn=input_fn_train, steps=100)

def input_fn_eval: # returns x, y
  pass
metrics = estimator.evaluate(input_fn=input_fn_eval, steps=10)
def input_fn_predict: # returns x, None
  pass
predictions = estimator.predict(input_fn=input_fn_predict)

Input of train and evaluate should have following features, otherwise there will be a KeyError:

  • if the head's weight_column is not None, a feature with key=weight_column whose value is a Tensor.
  • for each column in sequence_feature_columns:
    • a feature with key=column.name whose value is a SparseTensor.
  • for each column in context_feature_columns:
    • if column is a CategoricalColumn, a feature with key=column.name whose value is a SparseTensor.
    • if column is a WeightedCategoricalColumn, two features: the first with key the id column name, the second with key the weight column name. Both features' value must be a SparseTensor.
    • if column is a DenseColumn, a feature with key=column.name whose value is a Tensor.

Loss and predicted output are determined by the specified head.

head A Head instance. This specifies the model's output and loss function to be optimized.
sequence_feature_columns An iterable containing the FeatureColumns that represent sequential input. All items in the set should either be sequence columns (e.g. sequence_numeric_column) or constructed from one (e.g. embedding_column with sequence_categorical_column_* as input).
context_feature_columns An iterable containing the FeatureColumns for contextual input. The data represented by these columns will be replicated and given to the RNN at each timestep. These columns must be instances of classes derived from DenseColumn such as numeric_column, not the sequential variants.
units Iterable of integer number of hidden units per RNN layer. If set, cell_type must also be specified and rnn_cell_fn must be None.
cell_type A class producing a RNN cell or a string specifying the cell type. Supported strings are: 'simple_rnn', 'lstm', and 'gru'. If set, units must also be specified and rnn_cell_fn must be None.
rnn_cell_fn A function that returns a RNN cell instance that will be used to construct the RNN. If set, units and cell_type cannot be set. This is for advanced users who need additional customization beyond units and cell_type. Note that tf.keras.layers.StackedRNNCells is needed for stacked RNNs.
return_sequences A boolean indicating whether to return the last output in the output sequence, or the full sequence.
model_dir Directory to save model parameters, graph and etc. This can also be used to load checkpoints from the directory into a estimator to continue training a previously saved model.
optimizer An instance of tf.Optimizer or string specifying optimizer type. Defaults to Adagrad optimizer.
config RunConfig object to configure the runtime settings.

ValueError If units, cell_type, and rnn_cell_fn are not compatible.

Eager Compatibility

Estimators are not compatible with eager execution.

config

model_dir

model_fn Returns the model_fn which is bound to self.params.
params

Methods

eval_dir

View source

eval_dir(
    name=None
)

Shows the directory name where evaluation metrics are dumped.

Args
name Name of the evaluation if user needs to run multiple evaluations on different data sets, such as on training data vs test data. Metrics for different evaluations are saved in separate folders, and appear separately in tensorboard.

Returns
A string which is the path of directory contains evaluation metrics.

evaluate

View source

evaluate(
    input_fn, steps=None, hooks=None, checkpoint_path=None, name=None
)

Evaluates the model given evaluation data input_fn.

For each step, calls input_fn, which returns one batch of data. Evaluates until:

Args
input_fn A function that constructs the input data for evaluation. See Premade Estimators for more information. The function should construct and return one of the following:

  • A tf.data.Dataset object: Outputs of Dataset object must be a tuple (features, labels) with same constraints as below.
  • A tuple (features, labels): Where features is a tf.Tensor or a dictionary of string feature name to Tensor and labels is a Tensor or a dictionary of string label name to Tensor. Both features and labels are consumed by model_fn. They should satisfy the expectation of model_fn from inputs.
steps Number of steps for which to evaluate model. If None, evaluates until input_fn raises an end-of-input exception.
hooks List of tf.train.SessionRunHook subclass instances. Used for callbacks inside the evaluation call.
checkpoint_path Path of a specific checkpoint to evaluate. If None, the latest checkpoint in model_dir is used. If there are no checkpoints in model_dir, evaluation is run with newly initialized Variables instead of ones restored from checkpoint.
name Name of the evaluation if user needs to run multiple evaluations on different data sets, such as on training data vs test data. Metrics for different evaluations are saved in separate folders, and appear separately in tensorboard.

Returns
A dict containing the evaluation metrics specified in model_fn keyed by name, as well as an entry global_step which contains the value of the global step for which this evaluation was performed. For canned estimators, the dict contains the loss (mean loss per mini-batch) and the average_loss (mean loss per sample). Canned classifiers also