awfulstack with docstrings

Author: nlw0

base/abstractarray.jl

@@ -2599,6 +2599,248 @@ end
     Ai
 end
 
+"""
+    awfulstack(array_of_arrays)
+
+Concatenates a multi-dimensional array of arrays into a single array, seeing
+the input as a block array. The dimensions of the sub-arrays must match accordingly.
+
+# Examples
+
+Simple concatenation of vectors
+
+```jldoctest
+julia> hcat([1,2,3], [5,6,7])
+3×2 Matrix{Int64}:
+ 1  5
+ 2  6
+ 3  7
+
+julia> reduce(hcat, [[1,2,3], [5,6,7]])
+3×2 Matrix{Int64}:
+ 1  5
+ 2  6
+ 3  7
+
+julia> awfulstack([[1,2,3] [5,6,7]])
+6-element Vector{Int64}:
+ 1  5
+ 2  6
+ 3  7
+
+julia> awfulstack([[1,2,3], [5,6,7]])
+6-element Vector{Int64}:
+ 1
+ 2
+ 3
+ 5
+ 6
+ 7
+
+julia> awfulstack([[1,2,3], [5,6,7]]')
+1×6 Matrix{Int64}:
+ 1  2  3  5  6  7
+
+julia> awfulstack(permutedims.([[1,2,3], [5,6,7]]))
+2×3 Matrix{Int64}:
+ 1  2  3
+ 5  6  7
+```
+
+"Flatmap" behavior.
+```jldoctest
+julia> awfulstack(n -> -n:2:n, 1:3)
+9-element Vector{Int64}:
+ -1
+  1
+ -2
+  0
+  2
+ -3
+ -1
+  1
+  3
+```
+
+Image montage.
+
+```
+using TestImages, ImageView
+myimages = ["cameraman","resolution_test_512","plastic_bubbles_he_512", "pirate", "woman_darkhair", "walkbridge"]
+imagearray = testimage.(reshape(myimages,2,:))
+imshow(awfulstack(imagearray))
+```
+
+# Extended Help
+
+## More Examples
+
+Higher-dimension concatenation.
+
+```jldoctest
+julia> awfulstack([1 2]) do n reshape(n*4-3:n*4,2,2) end
+2×4 Matrix{Int64}:
+ 1  3  5  7
+ 2  4  6  8
+
+julia> awfulstack([1,2]) do n reshape(n*4-3:n*4,2,2) end
+4×2 Matrix{Int64}:
+ 1  3
+ 2  4
+ 5  7
+ 6  8
+
+julia> awfulstack([1;;;2;;;]) do n reshape(n*4-3:n*4,2,2) end
+2×2×2 Array{Int64, 3}:
+[:, :, 1] =
+ 1  3
+ 2  4
+
+[:, :, 2] =
+ 5  7
+ 6  8
+```
+
+Relationship to `eachcol` and `eachrow`.
+
+```jldoctest
+julia> m = reshape(1:15,3,5)
+3×5 reshape(::UnitRange{Int64}, 3, 5) with eltype Int64:
+ 1  4  7  10  13
+ 2  5  8  11  14
+ 3  6  9  12  15
+
+julia> lol = eachcol(m) |> collect
+5-element Vector{SubArray{Int64, 1, Base.ReshapedArray{Int64, 2, UnitRange{Int64}, Tuple{}}, Tuple{Base.Slice{Base.OneTo{Int64}}, Int64}, true}}:
+ [1, 2, 3]
+ [4, 5, 6]
+ [7, 8, 9]
+ [10, 11, 12]
+ [13, 14, 15]
+
+julia> awfulstack(lol)
+15-element Vector{Int64}:
+  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+
+julia> awfulstack(lol')
+1×15 Matrix{Int64}:
+ 1  2  3  4  5  6  7  8  9  10  11  12  13  14  15
+
+julia> awfulstack(permutedims(lol))
+3×5 Matrix{Int64}:
+ 1  4  7  10  13
+ 2  5  8  11  14
+ 3  6  9  12  15
+
+julia> lol = eachrow(m) |> collect
+3-element Vector{SubArray{Int64, 1, Base.ReshapedArray{Int64, 2, UnitRange{Int64}, Tuple{}}, Tuple{Int64, Base.Slice{Base.OneTo{Int64}}}, true}}:
+ [1, 4, 7, 10, 13]
+ [2, 5, 8, 11, 14]
+ [3, 6, 9, 12, 15]
+
+julia> awfulstack(permutedims(lol))
+5×3 Matrix{Int64}:
+  1   2   3
+  4   5   6
+  7   8   9
+ 10  11  12
+ 13  14  15
+
+julia> awfulstack(permutedims.(lol))
+3×5 Matrix{Int64}:
+ 1  4  7  10  13
+ 2  5  8  11  14
+ 3  6  9  12  15
+```
+
+Non-uniform array shapes with 3 dimensions.
+
+```jldoctest
+julia> myarrays = map([(j,k,l) for j in 1:2, k in 1:2, l in 1:2]) do (jkl)
+           reshape(1:prod((jkl)), jkl...)
+       end
+2×2×2 Array{Base.ReshapedArray{Int64, 3, UnitRange{Int64}, Tuple{}}, 3}:
+[:, :, 1] =
+ [1;;;]     [1 2;;;]
+ [1; 2;;;]  [1 3; 2 4;;;]
+
+[:, :, 2] =
+ [1;;; 2]        [1 2;;; 3 4]
+ [1; 2;;; 3; 4]  [1 3; 2 4;;; 5 7; 6 8]
+
+julia> arr = awfulstack(myarrays)
+3×3×3 Array{Int64, 3}:
+[:, :, 1] =
+ 1  1  2
+ 1  1  3
+ 2  2  4
+
+[:, :, 2] =
+ 1  1  2
+ 1  1  3
+ 2  2  4
+
+[:, :, 3] =
+ 2  3  4
+ 3  5  7
+ 4  6  8
+
+julia> arr == awfulstack([(j,k,l) for j in 1:2, k in 1:2, l in 1:2]) do (jkl)
+           reshape(1:prod((jkl)), jkl...)
+       end
+true
+```
+"""
+awfulstack(array_of_arrays) = awfulstack_(array_of_arrays)
+
+"""
+    awfulstack(f, c...)
+
+Equivalent to awfulstact(map(f, c...)). Implements flatmap behavior.
+
+# Example
+```jldoctest
+julia> Znm = [x for n in 1:3 for x in -n:2:n]
+9-element Vector{Int64}:
+ -1
+  1
+ -2
+  0
+  2
+ -3
+ -1
+  1
+  3
+
+julia> awfulstack(n -> -n:2:n, 1:3) == Znm
+true
+```
+"""
+awfulstack(f, c...) = awfulstack(map(f, c...))
+
+function awfulstack_(aoa; indices=(), mydim=ndims(aoa))
+    if mydim==1
+        reduce(catdim_(mydim), view(aoa,:,indices...))
+    else
+        reduce(catdim_(mydim), (awfulstack_(aoa, indices=(n, indices...), mydim=mydim-1) for n in 1:size(aoa, mydim)))
+    end
+end
+catdim_(dims) = (a,b) -> cat(a,b,dims=dims)
+
 ## Reductions and accumulates ##
 
 function isequal(A::AbstractArray, B::AbstractArray)

base/exports.jl

@@ -445,6 +445,7 @@ export
     sortperm!,
     sortslices,
     dropdims,
+    awfulstack,
     step,
     stride,
     strides,