Updates to README for TF Learn to remove references to "SKFlow" and update

tensorflower-gardener · tensorflower-gardener · commit 61dc340d0873 · 2016-09-20T12:33:28.000-07:00
code/resources.
Change: 133738295
diff --git a/tensorflow/contrib/learn/python/learn/README.md b/tensorflow/contrib/learn/python/learn/README.md
@@ -1,53 +1,44 @@
-# TF Learn (aka Scikit Flow)
+# TF Learn
 
-[![Join the chat at https://gitter.im/tensorflow/skflow](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/tensorflow/skflow?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-
-This is a simplified interface for TensorFlow, to get people started on predictive analytics and data mining.
-
-Library covers variety of needs from linear models to *Deep Learning* applications like text and image understanding.
+TF Learn is a simplified interface for TensorFlow, to get people started on predictive analytics and data mining. The library covers a variety of needs: from linear models to *Deep Learning* applications like text and image understanding.
 
 ### Why *TensorFlow*?
 
-- TensorFlow provides a good backbone for building different shapes of machine learning applications.
-- It will continue to evolve both in the distributed direction and as general pipelinining machinery.
+* TensorFlow provides a good backbone for building different shapes of machine learning applications.
+* It will continue to evolve both in the distributed direction and as general pipelinining machinery.
 
-### Why *TensorFlow Learn* (Scikit Flow)?
+### Why *TensorFlow Learn*?
 
-- To smooth the transition from the Scikit Learn world of one-liner machine learning into the more open world of building different shapes of ML models. You can start by using fit/predict and slide into TensorFlow APIs as you are getting comfortable.
-- To provide a set of reference models that would be easy to integrate with existing code.
+- To smooth the transition from the [scikit-learn](http://scikit-learn.org/stable/) world of one-liner machine learning into the more open world of building different shapes of ML models. You can start by using [fit](../../../../g3doc/api_docs/python/contrib.learn.md#Estimator.fit)/[predict](../../../../g3doc/api_docs/python/contrib.learn.md#Estimator.predict) and slide into TensorFlow APIs as you are getting comfortable.
+- To provide a set of reference models that will be easy to integrate with existing code.
 
 ## Installation
 
-Optionally you can install Scikit Learn and Pandas for additional functionality.
-
-Then you can simply import `learn` via `from tensorflow.contrib.learn` or use `tf.contrib.learn`.
+[Install TensorFlow](../../../../g3doc/get_started/os_setup.md), and then simply import `learn` via `from tensorflow.contrib.learn` or use `tf.contrib.learn`.
 
+Optionally you can install [scikit-learn](http://scikit-learn.org/stable/) and [pandas](http://pandas.pydata.org/) for additional functionality.
 
-### Tutorial
+### Tutorials
 
--  [Introduction to Scikit Flow and Why You Want to Start Learning
-   TensorFlow](https://medium.com/@ilblackdragon/tensorflow-tutorial-part-1-c559c63c0cb1)
--  [DNNs, Custom model and Digit Recognition
-   examples](https://medium.com/@ilblackdragon/tensorflow-tutorial-part-2-9ffe47049c92)
--  [Categorical Variables: One Hot vs Distributed
-   representation](https://medium.com/@ilblackdragon/tensorflow-tutorial-part-3-c5fc0662bc08)
--  [Scikit Flow Key Features Illustrated](http://terrytangyuan.github.io/2016/03/14/scikit-flow-intro/)
+- [TF Learn Quickstart](../../../../g3doc/tutorials/tflearn/index.md). Build, train, and evaluate a neural network with just a few lines of code.
+- [Linear Model](../../../../g3doc/tutorials/wide/index.md). Learn the basics of building linear models.
+- [Logging and Monitoring](../../../../g3doc/tutorials/monitors/index.md). Use the Monitor API to audit training of a neural network.
+- [Wide and Deep Learning](../../../../g3doc/tutorials/wide_and_deep/index.md). Jointly train a linear model and a deep neural network.
 -  More coming soon.
 
 ### Community
 
-- Twitter [#skflow](https://twitter.com/search?q=skflow&src=typd).
-- StackOverflow with [skflow tag](http://stackoverflow.com/questions/tagged/skflow) for questions and struggles.
-- Github [issues](https://github.com/tensorflow/tensorflow/issues) for technical discussions and feature requests.
-- [Gitter channel](https://gitter.im/tensorflow/skflow) for non-trivial discussions.
+- Twitter [#tensorflow](https://twitter.com/search?q=tensorflow&src=typd).
+- StackOverflow with [tensorflow tag](http://stackoverflow.com/questions/tagged/tensorflow) for questions and struggles.
+- GitHub [issues](https://github.com/tensorflow/tensorflow/issues) for technical discussions and feature requests.
 
 ### Usage
 
-Below are few simple examples of the API. For more examples, please see [examples](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/examples/skflow).
+Below are a few simple examples of the API. For more examples, please see [examples](https://www.tensorflow.org/code/tensorflow/examples/skflow).
 
-## General tips
+General tips:
 
--  It's useful to re-scale dataset before passing to estimator to 0 mean and unit standard deviation. Stochastic Gradient Descent doesn't always do the right thing when variable are very different scale.
+-  It's useful to rescale a dataset to 0 mean and unit standard deviation before passing it to an [`Estimator`](../../../../g3doc/api_docs/python/contrib.learn.md#estimators). [Stochastic Gradient Descent](https://en.wikipedia.org/wiki/Stochastic_gradient_descent) doesn't always do the right thing when variable are at very different scales.
 
 -  Categorical variables should be managed before passing input to the estimator.
 
@@ -60,9 +51,11 @@ import tensorflow.contrib.learn.python.learn as learn
 from sklearn import datasets, metrics
 
 iris = datasets.load_iris()
-classifier = learn.LinearClassifier(n_classes=3)
+feature_columns = learn.infer_real_valued_columns_from_input(iris.data)
+classifier = learn.LinearClassifier(n_classes=3, feature_columns=feature_columns)
 classifier.fit(iris.data, iris.target, steps=200, batch_size=32)
-score = metrics.accuracy_score(iris.target, classifier.predict(iris.data))
+iris_predictions = list(classifier.predict(iris.data, as_iterable=True))
+score = metrics.accuracy_score(iris.target, iris_predictions)
 print("Accuracy: %f" % score)
 ```
 
@@ -76,9 +69,11 @@ from sklearn import datasets, metrics, preprocessing
 
 boston = datasets.load_boston()
 x = preprocessing.StandardScaler().fit_transform(boston.data)
-regressor = learn.LinearRegressor()
+feature_columns = learn.infer_real_valued_columns_from_input(x)
+regressor = learn.LinearRegressor(feature_columns=feature_columns)
 regressor.fit(x, boston.target, steps=200, batch_size=32)
-score = metrics.mean_squared_error(regressor.predict(x), boston.target)
+boston_predictions = list(regressor.predict(x, as_iterable=True))
+score = metrics.mean_squared_error(boston_predictions, boston.target)
 print ("MSE: %f" % score)
 ```
 
@@ -91,9 +86,11 @@ import tensorflow.contrib.learn.python.learn as learn
 from sklearn import datasets, metrics
 
 iris = datasets.load_iris()
-classifier = learn.DNNClassifier(hidden_units=[10, 20, 10], n_classes=3)
+feature_columns = learn.infer_real_valued_columns_from_input(iris.data)
+classifier = learn.DNNClassifier(hidden_units=[10, 20, 10], n_classes=3, feature_columns=feature_columns)
 classifier.fit(iris.data, iris.target, steps=200, batch_size=32)
-score = metrics.accuracy_score(iris.target, classifier.predict(iris.data))
+iris_predictions = list(classifier.predict(iris.data, as_iterable=True))
+score = metrics.accuracy_score(iris.target, iris_predictions)
 print("Accuracy: %f" % score)
 ```
 
@@ -102,68 +99,122 @@ print("Accuracy: %f" % score)
 Example of how to pass a custom model to the Estimator:
 
 ```python
+from sklearn import datasets
+from sklearn import metrics
+import tensorflow as tf
+import tensorflow.contrib.layers.python.layers as layers
 import tensorflow.contrib.learn.python.learn as learn
-from sklearn import datasets, metrics
 
 iris = datasets.load_iris()
 
-def my_model(x, y):
-    """This is DNN with 10, 20, 10 hidden layers, and dropout of 0.5 probability."""
-    layers = learn.ops.dnn(x, [10, 20, 10], dropout=0.5)
-    return learn.models.logistic_regression(layers, y)
+def my_model(features, target):
+  """DNN with three hidden layers, and dropout of 0.1 probability."""
+  # Convert the target to a one-hot tensor of shape (length of features, 3) and
+  # with a on-value of 1 for each one-hot vector of length 3.
+  target = tf.one_hot(target, 3, 1, 0)
 
-classifier = learn.Estimator(model_fn=my_model, n_classes=3)
-classifier.fit(iris.data, iris.target)
-score = metrics.accuracy_score(iris.target, classifier.predict(iris.data))
-print("Accuracy: %f" % score)
-```
+  # Create three fully connected layers respectively of size 10, 20, and 10 with
+  # each layer having a dropout probability of 0.1.
+  features = layers.stack(features, layers.fully_connected, [10, 20, 10])
 
-## Saving / Restoring models
+  # Create two tensors respectively for prediction and loss.
+  prediction, loss = (
+      tf.contrib.learn.models.logistic_regression(features, target)
+  )
 
-Each estimator has a ``save`` method which takes folder path where all model information will be saved. For restoring you can just call ``learn.Estimator.restore(path)`` and it will return object of your class.
+  # Create a tensor for training op.
+  train_op = tf.contrib.layers.optimize_loss(
+      loss, tf.contrib.framework.get_global_step(), optimizer='Adagrad',
+      learning_rate=0.1)
 
-Some example code:
+  return {'class': tf.argmax(prediction, 1), 'prob': prediction}, loss, train_op
 
-```python
-classifier = learn.LinearRegressor()
-classifier.fit(...)
-classifier.save('/tmp/tf_examples/my_model_1/')
+classifier = learn.Estimator(model_fn=my_model)
+classifier.fit(iris.data, iris.target, steps=1000)
 
-new_classifier = Estimator.restore('/tmp/tf_examples/my_model_2')
-new_classifier.predict(...)
+y_predicted = [
+  p['class'] for p in classifier.predict(iris.data, as_iterable=True)]
+score = metrics.accuracy_score(iris.target, y_predicted)
+print('Accuracy: {0:f}'.format(score))
 ```
 
-## Summaries
+## Saving / Restoring models
 
-To get nice visualizations and summaries you can use ``logdir`` parameter on ``fit``. It will start writing summaries for ``loss`` and histograms for variables in your model. You can also add custom summaries in your custom model function by calling ``tf.summary`` and passing Tensors to report.
+Each estimator supports a `model_dir` argument, which takes a folder path where all model information will be saved:
 
 ```python
-classifier = learn.LinearRegressor()
-classifier.fit(x, y, logdir='/tmp/tf_examples/my_model_1/')
+classifier = learn.DNNClassifier(..., model_dir="/tmp/my_model")
 ```
 
-Then run next command in command line:
+If you run multiple `fit` operations on the same `Estimator`, training will resume where the last operation left off, e.g.:
+
+<pre><strong>classifier = learn.DNNClassifier(..., model_dir="/tmp/my_model")
+classifier.fit(..., steps=300)</strong>
+INFO:tensorflow:Create CheckpointSaverHook
+INFO:tensorflow:loss = 2.40115, step = 1
+INFO:tensorflow:Saving checkpoints for 1 into /tmp/leftoff/model.ckpt.
+INFO:tensorflow:loss = 0.338706, step = 101
+INFO:tensorflow:loss = 0.159414, step = 201
+INFO:tensorflow:Saving checkpoints for 300 into /tmp/leftoff/model.ckpt.
+INFO:tensorflow:Loss for final step: 0.0953846.
+
+<strong>classifier.fit(..., steps=300)</strong>
+INFO:tensorflow:Create CheckpointSaverHook
+INFO:tensorflow:loss = 0.113173, step = 301
+INFO:tensorflow:Saving checkpoints for 301 into /tmp/leftoff/model.ckpt.
+INFO:tensorflow:loss = 0.175782, step = 401
+INFO:tensorflow:loss = 0.119735, step = 501
+INFO:tensorflow:Saving checkpoints for 600 into /tmp/leftoff/model.ckpt.
+INFO:tensorflow:Loss for final step: 0.0518137.</pre>
+
+To restore checkpoints to a new `Estimator`, just pass it the same `model_dir` argument, e.g.:
+
+<pre><strong>classifier = learn.DNNClassifier(..., model_dir="/tmp/my_model")
+classifier.fit(..., steps=300)</strong>
+INFO:tensorflow:Create CheckpointSaverHook
+INFO:tensorflow:loss = 1.16335, step = 1
+INFO:tensorflow:Saving checkpoints for 1 into /tmp/leftoff/model.ckpt.
+INFO:tensorflow:loss = 0.176995, step = 101
+INFO:tensorflow:loss = 0.184573, step = 201
+INFO:tensorflow:Saving checkpoints for 300 into /tmp/leftoff/model.ckpt.
+INFO:tensorflow:Loss for final step: 0.0512496.
+
+<strong>classifier2 = learn.DNNClassifier(..., model_dir="/tmp/my_model")
+classifier2.fit(..., steps=300)</strong>
+INFO:tensorflow:Create CheckpointSaverHook
+INFO:tensorflow:loss = 0.0543797, step = 301
+INFO:tensorflow:Saving checkpoints for 301 into /tmp/leftoff/model.ckpt.
+INFO:tensorflow:loss = 0.101036, step = 401
+INFO:tensorflow:loss = 0.137956, step = 501
+INFO:tensorflow:Saving checkpoints for 600 into /tmp/leftoff/model.ckpt.
+INFO:tensorflow:Loss for final step: 0.0162506.</pre>
+
+## Summaries
+
+If you supply a `model_dir` argument to your `Estimator`s, TensorFlow will write summaries for ``loss`` and histograms for variables in this directory. (You can also add custom summaries in your custom model function by calling [Summary](../../../../g3doc/api_docs/python/train.md#summary-operations) operations.)
+
+To view the summaries in TensorBoard, run the following command, where `logdir` is the `model_dir` for your `Estimator`:
 
 ```shell
 tensorboard --logdir=/tmp/tf_examples/my_model_1
 ```
 
-and follow reported url.
+and then load the reported URL.
 
-Graph visualization: |Text classification RNN Graph|
+**Graph visualization**
 
-Loss visualization: |Text classification RNN Loss|
+![Text classification RNN Graph](https://raw.githubusercontent.com/tensorflow/skflow/master/g3doc/images/text_classification_rnn_graph.png)
 
-## More examples
+**Loss visualization**
 
-See [examples folder](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/examples/skflow) for:
+![Text classification RNN Loss](https://raw.githubusercontent.com/tensorflow/skflow/master/g3doc/images/text_classification_rnn_loss.png)
 
--  Easy way to handle categorical variables - words are just an example of categorical variable.
--  Text Classification - see examples for RNN, CNN on word and characters.
--  Language modeling and text sequence to sequence.
--  Images (CNNs) - see example for digit recognition.
--  More & deeper - different examples showing DNNs and CNNs
+## More examples
 
-![Text classification RNN Graph](https://raw.githubusercontent.com/tensorflow/skflow/master/g3doc/images/text_classification_rnn_graph.png)
+See the [examples folder](https://www.tensorflow.org/code/tensorflow/examples/skflow) for:
 
-![Text classification RNN Loss](https://raw.githubusercontent.com/tensorflow/skflow/master/g3doc/images/text_classification_rnn_loss.png)
+-  An easy way to handle [categorical variables](https://www.tensorflow.org/code/tensorflow/examples/skflow/text_classification.py) (words are just an example of a categorical variable)
+-  Text Classification: see examples for [RNN](https://www.tensorflow.org/code/tensorflow/examples/skflow/text_classification_character_rnn.py) and [CNN](https://www.tensorflow.org/code/tensorflow/examples/skflow/text_classification_character_cnn.py) on characters
+-  [Language modeling and text sequence to sequence](https://www.tensorflow.org/code/tensorflow/examples/skflow/language_model.py)
+-  [Digit recognition using a CNN](https://www.tensorflow.org/code/tensorflow/examples/skflow/digits.py)
+-  And much more!
