EVERYTHING IN THIS DIRECTORY IS DEPRECATED.

Using functions or classes will result in warnings.

Instructions for converting to current alternatives are included in the
warnings. A high-level overview is below.

## Canned Estimators

Many canned estimators (subclasses of `Estimator`) have equivalents in core:
`DNNClassifier`, `DNNRegressor`, `DNNEstimator`, `LinearClassifier`,
`LinearRegressor`, `DNNLinearCombinedClassifier` and
`DNNLinearCombinedRegressor`. They are exposed under `tf.estimator`.
`DNNEstimator`, `LinearEstimator` and `DNNLinearCombinedEstimator`
are exposed under `tf.contrib.estimator`.

To migrate to the new api, users need to take the following steps:

* Replace `tf.contrib.learn` with `tf.estimator`.
* If you subclass any of the estimators, stop doing that. You should be able to
  write a factory method that returns a canned estimator instead. If this is not
  possible (if you override methods from the canned estimator), consider writing
  a custom estimator instead. See `tf.estimator.Estimator`.
* Set `loss_reduction=tf.losses.Reduction.SUM_OVER_BATCH_SIZE` to preserve loss
  reduction as the average over batch.
* Some optimizer-related arguments are no longer passed in the estimator
  constructor. Instead, we provide methods that perform the same job by wrapping
  an optimizer. Specifically:
  *  `gradient_clip_norm`: Use `tf.contrib.estimator.clip_gradients_by_norm`
  *  `embedding_lr_multipliers`: Not supported.
  Other arguments:
  * `input_layer_min_slice_size`: Replaced by `input_layer_partitioner`
  * `enable_centered_bias`: Not supported. Dropping this argument is unlikely to
    harm your model.
  * `feature_engineering_fn`: Not supported. You can call your
    `feature_engineering_fn` inside your input_fn:
    ```python
    def new_input_fn():
      features, labels = old_input_fn()
      return feature_engineering_fn(features, labels)
    ```
* Use `tf.reshape` to reshape labels in your `input_fn`. `tf.estimator`
  classifiers and regressors expect labels as a 2D Tensor of shape
  `[batch_size, 1]`, or `[batch_size, n_labels]`. In contrast,
  `tf.contrib.learn` classifiers and regressors supported labels with shape
  `[batch_size]`.
* If you pass custom metrics from the `evaluate()` method call, use
  `tf.contrib.estimator.add_metrics`.
* Replace your `serving_input_fn` with a `serving_input_receiver_fn`.
  Note this should be entirely distinct from your training `input_fn`, so if you
  previously had one `input_fn` with different "modes", you should now factor
  that apart.  Where the former returned either a simple `(features, labels)`
  tuple or `InputFnOps`, you should now return a `ServingInputReceiver`.
  If you were generating your `serving_input_fn` using the
  `build_parsing_serving_input_fn` helper, you can simply drop in the
  replacement `build_parsing_serving_input_receiver_fn`.

Some remaining estimators/classes:

* `DynamicRnnEstimator`:  Consider a custom `model_fn`.
* `KMeansClustering`: Use `tf.contrib.factorization.KMeansClustering`.
* `LogisticRegressor`: Not supported. Instead, use `binary_classification_head`
  with a custom `model_fn`, or with `DNNEstimator`.
* `StateSavingRnnEstimator`: Consider a custom `model_fn`.
* SVM: Consider a custom `model_fn`.
* `LinearComposableModel` and `DNNComposableModel`: Not supported. 
  Consider `tf.contrib.estimator.DNNEstimator`, or write a custom model_fn.
* `MetricSpec`: Deprecated. For adding custom metrics to canned Estimators, use
  `tf.contrib.estimator.add_metrics`.

## Estimator
`tf.contrib.learn.Estimator` is migrated to `tf.estimator.Estimator`.

To migrate, users need to take the following steps:

* Replace `tf.contrib.learn.Estimator` with `tf.estimator.Estimator`.
* If you pass a `config` argument to `Estimator`, this must be
  `tf.estimator.RunConfig`. You may need to edit your code accordingly.
* Edit your `model_fn` to return `tf.estimator.EstimatorSpec`. Refer to
  `EstimatorSpec` for documentation of specific fields.
* If your `model_fn` uses the `mode` argument, use `tf.estimator.ModeKeys`.

Some related classes:
* `Evaluable`, `Trainable`: Not supported, merged into `tf.estimator.Estimator`.
* ExportStrategy: Replaced by `tf.estimator.Exporter`.

## Head/MultiHead
These classes are now supported under `tf.contrib.estimator`, e.g.
`tf.contrib.estimator.multi_class_head` and `tf.contrib.estimator.multi_head`.

Some differences:

* `multi_class_head`: If you use `tf.contrib.learn.multi_class_head` with
  `n_classes=2`, switch to `tf.contrib.estimator.binary_classification_head`.
* `loss_only_head`: Not supported.
* `poisson_regression_head`: Not supported (yet).
* `binary_svm_head`: Not supported (yet).
* `no_op_train_fn`: Replace it with `tf.no_op`.

Some arguments are renamed, please refer to documentation. In addition:

* `loss_fn`: Supported for `multi_label_head`. If you need it for other heads,
  please open an issue.
* `metric_class_ids`: Not supported (yet).
* `enable_centered_bias`: Not supported. Dropping this argument is unlikely to
  harm your model.
* `label_name`: Not needed in `tf.estimator`. If you don’t use `multi_head`,
  drop this argument. If you use `multi_head`, refer to
  `tf.contrib.estimator.multi_head` documentation.

## Experiment Class - Distributed Training Tooling

Switch to `tf.estimator.train_and_evaluate`. Some differences:

* Most of the constructor arguments, like `train_input_fn`, `eval_input_fn`,
  should be wrapped into `tf.estimator.TrainSpec` and `tf.estimator.EvalSpec`.
* Remove the `experiment_fn`. Instead, create the `Estimator`,
  `train_spec` and `eval_spec`, then call `tf.estimator.train_and_evaluate`
  directly.
* Inside `tf.estimator.EvalSpec`, the `exporter` field is the replacement
  for `export_strategy`. To be precise, `tf.estimator.LatestExporter` is the
  replacement for `tf.contrib.learn.make_export_strategy`. If you want to export
  only at the end of training  use `tf.estimator.FinalExporter`.
* If the `TF_CONFIG` environment variable is constructed manually, please read
  the `train_and_evaluate` documentation for the new requirementds (in
  particular, the chief node and evaluator node).

## Others Classes and Functions

* `tf.contrib.learn.datasets` is deprecated. We are adding ready to use datasets
  to tensorflow/models. Many smaller datasets are available from other sources,
  such as scikits.learn. Some Python processing may have to be written, but this
  is straightforward to implement using the standard modules.
* `tf.contrib.learn.preprocessing`: Deprecated. The python-only preprocessing
  functions are not a good fit for TensorFlow. Please use `tf.data`, and
  consider tensorflow/transform for more complex use cases.
* `tf.contrib.learn.models`: Not supported, use canned estimators instead.
* `tf.contrib.learn.monitors`: Implement `SessionRunHook` instead. Hook
  implementations are in `tf.train`.
* `tf.contrib.learn.learn_io`: Use the methods in `tf.estimator.inputs`, such as
  `tf.estimator.inputs.numpy_input_fn`. Some utility functions have no
  equivalent, we encourage the use of `tf.data`.