An estimator is a rule that calculates an estimate of a given quantity. Estimators are used to train and evaluate TensorFlow models. Each estimator is an implementation of a particular type of ML algorithm. They currently support regression and classification problems. A list of the available estimators includes LinearRegressor/Classifier, DNNRegressor/Classifier, DNNLinearCombinedRegressor/Classifier, TensorForestEstimator, SVM, LogisticRegressor, and a generic estimator that can be used to construct a custom model for either classification or regression problems. This provides a wide range of state-of-art ML algorithms, as well as the building blocks users need to construct their own algorithms.

Graph actions contain all the complicated logic for distributed training, inference, and the evaluation of a model. They are built on top of TensorFlow's low-level APIs; these complexities are hidden away from users so that they can focus on using the simplified interface to conduct their research. Estimators can then be distributed using multiple machines and devices, and all extended estimators get this functionality for free.

For example, tf.estimator.RunConfig specifies the runtime configurations for an Estimator run, providing the required parameters such as the number of cores to be used and the amount of GPU memory to be used. It also contains a ClusterConfig that specifies the configuration for a distributed run. It configures the tasks, clusters, master nodes, parameter servers, and everything else.

Similar to libraries such as pandas, a high-level DataFrame module was included in tf.estimator to facilitate many common data reading/parsing tasks from resources such as TensorFlow.

To illustrate the basic functionalities of the tf.estimator module, we will start by building a basic deep neural network (DNN) model and training it on the Iris dataset with the aim of predicting flower species based on sepal/petal geometry. The Iris dataset contains 150 rows of data, comprising 50 samples from each of three related Iris species: Iris Setosa, Iris Virginica, and Iris Versicolor. Each row contains the following data for each flower sample: sepal length, sepal width, petal length, petal width, and flower species. Flower species are represented as integers, with 0 denoting Iris Setosa, 1 denoting Iris Versicolor, and 2 denoting Iris Virginica:

Figure 1: Iris dataset

The example described in this section, premade_estimator.py, is downloadable from https://github.com/tensorflow/models/blob/master/samples/core/get_started/premade_estimator.py.

To fetch the training data, iris_data.py is used, downloadable from https://github.com/tensorflow/models/blob/master/samples/core/get_started/iris_data.py.

The Iris dataset is randomized and split into two separate CSVs; the first is the training set of 120 samples (iris_training.csv):

TRAIN_URL = "http://download.tensorflow.org/data/iris_training.csv"

The second is the testing set of 30 samples (iris_test.csv):

TEST_URL = "http://download.tensorflow.org/data/iris_test.csv"

Here you find the feature fields:

CSV_COLUMN_NAMES = ['SepalLength', 'SepalWidth',
                    'PetalLength', 'PetalWidth', 'Species']

Here you find the species to classify:

SPECIES = ['Setosa', 'Versicolor', 'Virginica']

Training and testing data are loaded using the iris_data.load_data() function:

(train_x, train_y), (test_x, test_y) = iris_data.load_data()

tf.estimator offers a variety of predefined estimators that can be used to run training and evaluation operations on input data.

Here we'll configure a DNN Classifier model to fit the Iris data. Using tf.estimator, we instantiate a tf.estimator.DNNClassifier with just a couple of lines of code. The code above defines the model's features, which specifies the datatypes for the features in the dataset:

my_feature_columns = []
for key in train_x.keys():
 my_feature_columns.append(tf.feature_column.numeric_column(key=key))

All the feature data is continuous, so tf.feature_column.numeric_column is the appropriate function to use to construct the feature columns. There are four features in the dataset (sepal width, sepal height, petal width, and petal height), so the shape must be set to [4] to hold all the data.

Now let's build a classifier, using the DNNClassifier model:

classifier = tf.estimator.DNNClassifier(
        feature_columns=my_feature_columns,
        hidden_units=[10, 10],
        n_classes=3)

DNNClassifier model uses the following arguments:

Define the input pipeline (input_fn) and train the data using the train method. The number of training steps is 1000:

classifier.train(
        input_fn=lambda:iris_data.train_input_fn(train_x, train_y,
                                                 args.batch_size),
        steps=args.train_steps)

The model's accuracy is evaluated using the evaluate method:

eval_result = classifier.evaluate(
        input_fn=lambda:iris_data.eval_input_fn(test_x, test_y,
                                                args.batch_size))

print('
Test set accuracy: {accuracy:0.3f}
'.format(**eval_result))

Like the method train, evaluate takes an input function that builds its input pipeline. evaluate returns a dict with the evaluation results.

The code example (premade_estimator.py) outputs training logs followed by some predictions against the test set:

INFO:tensorflow:loss = 120.53493, step = 1
INFO:tensorflow:global_step/sec: 437.609
INFO:tensorflow:loss = 14.973656, step = 101 (0.291 sec)
INFO:tensorflow:global_step/sec: 369.482
INFO:tensorflow:loss = 8.025629, step = 201 (0.248 sec)
INFO:tensorflow:global_step/sec: 267.963
INFO:tensorflow:loss = 7.3872843, step = 301 (0.364 sec)
INFO:tensorflow:global_step/sec: 337.761
INFO:tensorflow:loss = 7.1775312, step = 401 (0.260 sec)
INFO:tensorflow:global_step/sec: 684.081
INFO:tensorflow:loss = 6.1282234, step = 501 (0.146 sec)
INFO:tensorflow:global_step/sec: 686.175
INFO:tensorflow:loss = 7.441858, step = 601 (0.146 sec)
INFO:tensorflow:global_step/sec: 731.402
INFO:tensorflow:loss = 4.633889, step = 701 (0.137 sec)
INFO:tensorflow:global_step/sec: 687.698
INFO:tensorflow:loss = 8.395943, step = 801 (0.145 sec)
INFO:tensorflow:global_step/sec: 687.174
INFO:tensorflow:loss = 6.0668287, step = 901 (0.146 sec)
INFO:tensorflow:Saving checkpoints for 1000 into C:UsersGIANCA~1AppDataLocalTemp	mp9yaobdrgmodel.ckpt.
INFO:tensorflow:Loss for final step: 7.467471.
INFO:tensorflow:Starting evaluation at 2018-03-03-14:11:13
INFO:tensorflow:Restoring parameters from C:UsersGIANCA~1AppDataLocalTemp	mp9yaobdrgmodel.ckpt-1000
INFO:tensorflow:Finished evaluation at 2018-03-03-14:11:14
INFO:tensorflow:Saving dict for global step 1000: accuracy = 0.96666664, average_loss = 0.060853884, global_step = 1000, loss = 1.8256165

Test set accuracy: 0.967

INFO:tensorflow:Restoring parameters from C:UsersGIANCA~1AppDataLocalTemp	mp9yaobdrgmodel.ckpt-1000

We can use the trained model to predict the species of an iris flower based on some unlabeled measurements.

Let's consider the following flower samples:

expected = ['Setosa', 'Versicolor', 'Virginica']
    predict_x = {
        'SepalLength': [5.1, 5.9, 6.9],
        'SepalWidth': [3.3, 3.0, 3.1],
        'PetalLength': [1.7, 4.2, 5.4],
        'PetalWidth': [0.5, 1.5, 2.1],
    }

As with training and evaluation, we make predictions using a single function call, via the predict method:

    predictions = classifier.predict(
        input_fn=lambda:iris_data.eval_input_fn(predict_x,
                                                labels=None,
         batch_size=args.batch_size))

    for pred_dict, expec in zip(predictions, expected):
        template = ('
Prediction is "{}" ({:.1f}%), expected "{}"')
        class_id = pred_dict['class_ids'][0]
        probability = pred_dict['probabilities'][class_id]
        print(template.format(iris_data.SPECIES[class_id],
                              100 * probability, expec))

The preceding code yields the following output:

Prediction is "Setosa" (99.8%), expected "Setosa"

Prediction is "Versicolor" (99.8%), expected "Versicolor"

Prediction is "Virginica" (97.4%), expected "Virginica"