one hot docs

docs/make.jl

@@ -14,6 +14,8 @@ makedocs(modules=[Flux],
                   "Training Models" =>
                     ["Optimisers" => "training/optimisers.md",
                      "Training" => "training/training.md"],
+                  "Data Munging" =>
+                    ["One-Hot Encoding" => "data/onehot.md"],
                   "Contributing & Help" => "contributing.md"])
 
 deploydocs(

docs/src/data/onehot.md

@@ -0,0 +1,54 @@
+# One-Hot Encoding
+
+It's common to encode categorical variables (like `true`, `false` or `cat`, `dog`) in "one-of-k" or ["one-hot"](https://en.wikipedia.org/wiki/One-hot) form. Flux provides the `onehot` function to make this easy.
+
+```
+julia> using Flux: onehot
+
+julia> onehot(:b, [:a, :b, :c])
+3-element Flux.OneHotVector:
+ false
+  true
+ false
+
+julia> onehot(:c, [:a, :b, :c])
+3-element Flux.OneHotVector:
+ false
+ false
+  true
+```
+
+The inverse is `argmax` (which can take a general probability distribution, as well as just booleans).
+
+```julia
+julia> argmax(ans, [:a, :b, :c])
+:c
+
+julia> argmax([true, false, false], [:a, :b, :c])
+:a
+
+julia> argmax([0.3, 0.2, 0.5], [:a, :b, :c])
+:c
+```
+
+## Batches
+
+`onehotbatch` creates a batch (matrix) of one-hot vectors, and `argmax` treats matrices as batches.
+
+```julia
+julia> using Flux: onehotbatch
+
+julia> onehotbatch([:b, :a, :b], [:a, :b, :c])
+3×3 Flux.OneHotMatrix:
+ false   true  false
+  true  false   true
+ false  false  false
+
+julia> onecold(ans, [:a, :b, :c])
+3-element Array{Symbol,1}:
+  :b
+  :a
+  :b
+```
+
+Note that these operations returned `OneHotVector` and `OneHotMatrix` rather than `Array`s. `OneHotVector`s behave like normal vectors but avoid any unnecessary cost compared to using an integer index directly.. For example, multiplying a matrix with a one-hot vector simply slices out the relevant row of the matrix under the hood.

docs/src/models/recurrence.md

@@ -1,3 +1,5 @@
+# Recurrent Models
+
 ## Recurrent Cells
 
 In the simple feedforward case, our model `m` is a simple function from various inputs `xᵢ` to predictions `yᵢ`. (For example, each `x` might be an MNIST digit and each `y` a digit label.) Each prediction is completely independent of any others, and using the same `x` will always produce the same `y`.

docs/src/training/training.md

@@ -1,3 +1,5 @@
+# Training
+
 To actually train a model we need three things:
 
 * A *loss function*, that evaluates how well a model is doing given some input data.

src/onehot.jl

@@ -24,8 +24,8 @@ Base.hcat(x::OneHotVector, xs::OneHotVector...) = OneHotMatrix([x, xs...])
 onehot(l, labels) = OneHotVector(findfirst(labels, l), length(labels))
 onehotbatch(ls, labels) = OneHotMatrix([onehot(l, labels) for l in ls])
 
-onecold(y::AbstractVector, labels = 1:length(y)) =
+argmax(y::AbstractVector, labels = 1:length(y)) =
   labels[findfirst(y, maximum(y))]
 
-onecold(y::AbstractMatrix, l...) =
-  squeeze(mapslices(y -> onecold(y, l...), y, 1), 1)
+argmax(y::AbstractMatrix, l...) =
+  squeeze(mapslices(y -> argmax(y, l...), y, 1), 1)

src/utils.jl

@@ -17,7 +17,7 @@ function accuracy(m, data)
   for (x, y) in data
     x, y = tobatch.((x, y))
     n += size(x, 1)
-    correct += sum(onecold(m(x)) .== onecold(y))
+    correct += sum(argmax(m(x)) .== argmax(y))
   end
   return correct/n
 end