1EVERYTHING IN THIS DIRECTORY IS DEPRECATED.
2
3Using functions or classes will result in warnings.
4
5Instructions for converting to current alternatives are included in the
6warnings. A high-level overview is below.
7
8## Canned Estimators
9
10Many canned estimators (subclasses of `Estimator`) have equivalents in core
11exposed under `tf.estimator`:
12`DNNClassifier`, `DNNRegressor`, `DNNEstimator`, `LinearClassifier`,
13`LinearRegressor`, `LinearEstimator`, `DNNLinearCombinedClassifier`,
14`DNNLinearCombinedRegressor` and `DNNLinearCombinedEstimator`.
15
16To migrate to the new api, users need to take the following steps:
17
18* Replace `tf.contrib.learn` with `tf.estimator`.
19* If you subclass any of the estimators, stop doing that. You should be able to
20  write a factory method that returns a canned estimator instead. If this is not
21  possible (if you override methods from the canned estimator), consider writing
22  a custom estimator instead. See `tf.estimator.Estimator`.
23* Set `loss_reduction=tf.losses.Reduction.SUM_OVER_BATCH_SIZE` to preserve loss
24  reduction as the average over batch.
25* Some optimizer-related arguments are no longer passed in the estimator
26  constructor. Instead, we provide methods that perform the same job by wrapping
27  an optimizer. Specifically:
28  *  `gradient_clip_norm`: Use `tf.contrib.estimator.clip_gradients_by_norm`
29  *  `embedding_lr_multipliers`: Not supported.
30  Other arguments:
31  * `input_layer_min_slice_size`: Replaced by `input_layer_partitioner`
32  * `enable_centered_bias`: Not supported. Dropping this argument is unlikely to
33    harm your model.
34  * `feature_engineering_fn`: Not supported. You can call your
35    `feature_engineering_fn` inside your input_fn:
36    ```python
37    def new_input_fn():
38      features, labels = old_input_fn()
39      return feature_engineering_fn(features, labels)
40    ```
41* Use `tf.reshape` to reshape labels in your `input_fn`. `tf.estimator`
42  classifiers and regressors expect labels as a 2D Tensor of shape
43  `[batch_size, 1]`, or `[batch_size, n_labels]`. In contrast,
44  `tf.contrib.learn` classifiers and regressors supported labels with shape
45  `[batch_size]`.
46* If you pass custom metrics from the `evaluate()` method call, use
47  `tf.estimator.add_metrics`.
48* Replace your `serving_input_fn` with a `serving_input_receiver_fn`.
49  Note this should be entirely distinct from your training `input_fn`, so if you
50  previously had one `input_fn` with different "modes", you should now factor
51  that apart.  Where the former returned either a simple `(features, labels)`
52  tuple or `InputFnOps`, you should now return a `ServingInputReceiver`.
53  If you were generating your `serving_input_fn` using the
54  `build_parsing_serving_input_fn` helper, you can simply drop in the
55  replacement `build_parsing_serving_input_receiver_fn`.
56
57Some remaining estimators/classes:
58
59* `DynamicRnnEstimator`:  Consider a custom `model_fn`.
60* `KMeansClustering`: Use `tf.contrib.factorization.KMeansClustering`.
61* `LogisticRegressor`: Not supported. Instead, use `binary_classification_head`
62  with a custom `model_fn`, or with `DNNEstimator`.
63* `StateSavingRnnEstimator`: Consider a custom `model_fn`.
64* SVM: Consider a custom `model_fn`.
65* `LinearComposableModel` and `DNNComposableModel`: Not supported.
66  Consider `tf.contrib.estimator.DNNEstimator`, or write a custom model_fn.
67* `MetricSpec`: Deprecated. For adding custom metrics to canned Estimators, use
68  `tf.estimator.add_metrics`.
69
70## Estimator
71`tf.contrib.learn.Estimator` is migrated to `tf.estimator.Estimator`.
72
73To migrate, users need to take the following steps:
74
75* Replace `tf.contrib.learn.Estimator` with `tf.estimator.Estimator`.
76* If you pass a `config` argument to `Estimator`, this must be
77  `tf.estimator.RunConfig`. You may need to edit your code accordingly.
78* Edit your `model_fn` to return `tf.estimator.EstimatorSpec`. Refer to
79  `EstimatorSpec` for documentation of specific fields.
80* If your `model_fn` uses the `mode` argument, use `tf.estimator.ModeKeys`.
81
82Some related classes:
83* `Evaluable`, `Trainable`: Not supported, merged into `tf.estimator.Estimator`.
84* ExportStrategy: Replaced by `tf.estimator.Exporter`.
85
86## Head/MultiHead
87These classes are now supported under `tf.contrib.estimator`, e.g.
88`tf.contrib.estimator.multi_class_head` and `tf.contrib.estimator.multi_head`.
89
90Some differences:
91
92* `multi_class_head`: If you use `tf.contrib.learn.multi_class_head` with
93  `n_classes=2`, switch to `tf.contrib.estimator.binary_classification_head`.
94* `loss_only_head`: Not supported.
95* `poisson_regression_head`: Not supported (yet).
96* `binary_svm_head`: Not supported (yet).
97* `no_op_train_fn`: Replace it with `tf.no_op`.
98
99Some arguments are renamed, please refer to documentation. In addition:
100
101* `loss_fn`: Supported for `multi_label_head`. If you need it for other heads,
102  please open an issue.
103* `metric_class_ids`: Not supported (yet).
104* `enable_centered_bias`: Not supported. Dropping this argument is unlikely to
105  harm your model.
106* `label_name`: Not needed in `tf.estimator`. If you don’t use `multi_head`,
107  drop this argument. If you use `multi_head`, refer to
108  `tf.contrib.estimator.multi_head` documentation.
109
110## Experiment Class - Distributed Training Tooling
111
112Switch to `tf.estimator.train_and_evaluate`. Some differences:
113
114*   Most of the constructor arguments, like `train_input_fn`, `eval_input_fn`,
115    should be wrapped into `tf.estimator.TrainSpec` and `tf.estimator.EvalSpec`.
116*   Remove the `experiment_fn`. Instead, create the `Estimator`, `train_spec`
117    and `eval_spec`, then call `tf.estimator.train_and_evaluate` directly.
118*   Inside `tf.estimator.EvalSpec`, the `exporter` field is the replacement for
119    `export_strategy`. To be precise, `tf.estimator.LatestExporter` is the
120    replacement for `tf.contrib.learn.make_export_strategy`. If you want to
121    export only at the end of training use `tf.estimator.FinalExporter`.
122*   If the `TF_CONFIG` environment variable is constructed manually, please read
123    the `train_and_evaluate` documentation for the new requirements (in
124    particular, the chief node and evaluator node).
125
126## Others Classes and Functions
127
128* `tf.contrib.learn.datasets` is deprecated. We are adding ready to use datasets
129  to tensorflow/models. Many smaller datasets are available from other sources,
130  such as scikits.learn. Some Python processing may have to be written, but this
131  is straightforward to implement using the standard modules.
132* `tf.contrib.learn.preprocessing`: Deprecated. The python-only preprocessing
133  functions are not a good fit for TensorFlow. Please use `tf.data`, and
134  consider tensorflow/transform for more complex use cases.
135* `tf.contrib.learn.models`: Not supported, use canned estimators instead.
136* `tf.contrib.learn.monitors`: Implement `SessionRunHook` instead. Hook
137  implementations are in `tf.train`.
138* `tf.contrib.learn.learn_io`: Use the methods in `tf.estimator.inputs`, such as
139  `tf.estimator.inputs.numpy_input_fn`. Some utility functions have no
140  equivalent, we encourage the use of `tf.data`.
141
142