README.md
1 # Labels for TensorFlow
2
3 LabeledTensor is a library for adding semantically meaningful dimension and
4 coordinate labels to tensors in Tensorflow.
5
6 LabeledTensor 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
18 labels along that axis (e.g., `("red", "green", "blue")`) in the form of a
19 tuple stored in `Axis.labels`.
20
21 Operations on `LabeledTensors` use, preserve and transform axis names and
22 labels.
23
24 ## Quick start
25
26 Try 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
53 LabeledTensor has wrappers for [quite a
54 few](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/contrib/labeled_tensor/__init__.py)
55 TensorFlow ops.
56
57 To easily add your own, you can use the `define_unary_op`, `define_binary_op`
58 and `define_reduce_op` functions, e.g.,
59
60 log = lt.define_unary_op('log', tf.log)
61
62 ## Questions
63
64 Please reach out to the authors:
65
66 - Stephan Hoyer (shoyer (a] google.com, github.com/shoyer)
67 - Eric Christiansen (ericmc (a] google.com, github.com/emchristiansen)
68