1# Labels for TensorFlow 2 3LabeledTensor is a library for adding semantically meaningful dimension and 4coordinate labels to tensors in Tensorflow. 5 6LabeledTensor was inspired by [xarray](http://xarray.pydata.org) and 7[pandas](http://pandas.pydata.org), projects that adds labels to NumPy array. 8 9## Data model 10 11`LabeledTensor` is an immutable object consisting of two components: 12 13- `tensor`: the `tf.Tensor` object containing the labeled tensor's data. 14- `axes`: an OrderedDict-like object with keys given by axis names (e.g., 15 ``"channel"``) and values given by `Axis` objects. 16 17`Axis` objects keep track of the size of a dimension and, optionally, coordinate 18labels along that axis (e.g., `("red", "green", "blue")`) in the form of a 19tuple stored in `Axis.labels`. 20 21Operations on `LabeledTensors` use, preserve and transform axis names and 22labels. 23 24## Quick start 25 26Try out the following snippet in a script or Jupyter notebook: 27 28 import tensorflow as tf 29 30 lt = tf.contrib.labeled_tensor 31 32 # Create two LabeledTensors: 33 raw_image = tf.ones((299, 299, 3)) 34 axes = ['row', 'column', ('channel', ['red', 'green', 'blue'])] 35 image = lt.LabeledTensor(raw_image, axes) 36 assert image.tensor is raw_image 37 weights = lt.LabeledTensor(tf.constant([0.1, 0.3, 0.6]), 38 [image.axes['channel']]) 39 40 # Examples of valid operations: 41 lt.transpose(image, ['column', 'row', 'channel']) 42 lt.reshape(image, ['row', 'column'], ['pixel']) 43 lt.concat([image, image], 'row') 44 lt.reduce_sum(image, ['channel']) 45 lt.select(image, {'channel': 'red'}) 46 lt.cast(image / 256.0, tf.uint8) 47 image * weights 48 lt.matmul(image[0, :, :], weights) 49 tf.cos(image) # automatically converts to tf.Tensor 50 51## Adding a custom op 52 53LabeledTensor has wrappers for [quite a 54few](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/contrib/labeled_tensor/__init__.py) 55TensorFlow ops. 56 57To easily add your own, you can use the `define_unary_op`, `define_binary_op` 58and `define_reduce_op` functions, e.g., 59 60 log = lt.define_unary_op('log', tf.log) 61 62## Questions 63 64Please reach out to the authors: 65 66- Stephan Hoyer (shoyer@google.com, github.com/shoyer) 67- Eric Christiansen (ericmc@google.com, github.com/emchristiansen) 68