Longer README for tf.contrib.labeled_tensor

PiperOrigin-RevId: 173966577

1 files changed, 60 insertions, 1 deletions

diff --git a/tensorflow/contrib/labeled_tensor/README.md b/tensorflow/contrib/labeled_tensor/README.md
index 50c6750fd0..adce979e2a 100644
--- a/tensorflow/contrib/labeled_tensor/README.md
+++ b/tensorflow/contrib/labeled_tensor/README.md
@@ -3,6 +3,65 @@
 LabeledTensor is a library for adding semantically meaningful dimension and
 coordinate labels to tensors in Tensorflow.
 
-Maintainers:
+LabeledTensor was inspired by [xarray](http://xarray.pydata.org) and
+[pandas](http://pandas.pydata.org), projects that adds labels to NumPy array.
+
+## Data model
+
+`LabeledTensor` is an immutable object consisting of two components:
+
+- `tensor`: the `tf.Tensor` object containing the labeled tensor's data.
+- `axes`: an OrderedDict-like object with keys given by axis names (e.g.,
+  ``"channel"``) and values given by `Axis` objects.
+
+`Axis` objects keep track of the size of a dimension and, optionally, coordinate
+labels along that axis (e.g., `("red", "green", "blue")`) in the form of a
+tuple stored in `Axis.labels`.
+
+Operations on `LabeledTensors` use, preserve and transform axis names and
+labels.
+
+## Quick start
+
+Try out the following snippet in a script or Jupyter notebook:
+
+    import tensorflow as tf
+
+    lt = tf.contrib.labeled_tensor
+
+    # Create two LabeledTensors:
+    raw_image = tf.ones((299, 299, 3))
+    axes = ['row', 'column', ('channel', ['red', 'green', 'blue'])]
+    image = lt.LabeledTensor(raw_image, axes)
+    assert image.tensor is raw_image
+    weights = lt.LabeledTensor(tf.constant([0.1, 0.3, 0.6]),
+                               [image.axes['channel']])
+
+    # Examples of valid operations:
+    lt.transpose(image, ['column', 'row', 'channel'])
+    lt.reshape(image, ['row', 'column'], ['pixel'])
+    lt.concat([image, image], 'row')
+    lt.reduce_sum(image, ['channel'])
+    lt.select(image, {'channel': 'red'})
+    lt.cast(image / 256.0, tf.uint8)
+    image * weights
+    lt.matmul(image[0, :, :], weights)
+    tf.cos(image)  # automatically converts to tf.Tensor
+
+## Adding a custom op
+
+LabeledTensor has wrappers for [quite a
+few](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/contrib/labeled_tensor/__init__.py)
+TensorFlow ops.
+
+To easily add your own, you can use the `define_unary_op`, `define_binary_op`
+and `define_reduce_op` functions, e.g.,
+
+    log = lt.define_unary_op('log', tf.log)
+
+## Questions
+
+Please reach out to the authors:
+
 - Stephan Hoyer (shoyer@google.com, github.com/shoyer)
 - Eric Christiansen (ericmc@google.com, github.com/emchristiansen)