DimStacks

An AbstractDimStack represents a collection of AbstractDimArray layers that share some or all dimensions. For any two layers, a dimension of the same name must have the identical lookup - in fact only one is stored for all layers to enforce this consistency.

julia> using DimensionalData

julia> x, y = X(1.0:10.0), Y(5.0:10.0)

↓ X 1.0:1.0:10.0,
→ Y 5.0:1.0:10.0

julia> st = DimStack((a=rand(x, y), b=rand(x, y), c=rand(y), d=rand(x)))

╭───────────────╮
│ 10×6 DimStack │
├───────────────┴──────────────────────────────────────────── dims ┐
  ↓ X Sampled{Float64} 1.0:1.0:10.0 ForwardOrdered Regular Points,
  → Y Sampled{Float64} 5.0:1.0:10.0 ForwardOrdered Regular Points
├────────────────────────────────────────────────────────── layers ┤
  :a eltype: Float64 dims: X, Y size: 10×6
  :b eltype: Float64 dims: X, Y size: 10×6
  :c eltype: Float64 dims: Y size: 6
  :d eltype: Float64 dims: X size: 10
└──────────────────────────────────────────────────────────────────┘

The behaviour of a DimStack is at times like a NamedTuple of DimArray and, others an AbstractArray of NamedTuple.

NamedTuple-like indexing

Layers can be accessed with .name or [:name]

julia> st.a

╭────────────────────────────╮
│ 10×6 DimArray{Float64,2} a │
├────────────────────────────┴─────────────────────────────── dims ┐
  ↓ X Sampled{Float64} 1.0:1.0:10.0 ForwardOrdered Regular Points,
  → Y Sampled{Float64} 5.0:1.0:10.0 ForwardOrdered Regular Points
└──────────────────────────────────────────────────────────────────┘
  ↓ →  5.0        6.0         7.0        8.0        9.0        10.0
  1.0  0.611279   0.00878657  0.133507   0.115586   0.882169    0.231272
  2.0  0.450577   0.915538    0.0990459  0.821471   0.0312095   0.665489
  3.0  0.537404   0.487919    0.116492   0.823999   0.525081    0.904851
  4.0  0.416854   0.734164    0.240681   0.509963   0.647812    0.731897
  5.0  0.987026   0.878193    0.505406   0.504967   0.60802     0.744053
  6.0  0.511068   0.633195    0.863719   0.888981   0.204186    0.193596
  7.0  0.0430107  0.243751    0.166553   0.204387   0.613296    0.0889836
  8.0  0.324693   0.0655892   0.54072    0.447854   0.0460139   0.422381
  9.0  0.320438   0.918784    0.255286   0.867458   0.417923    0.968613
 10.0  0.728709   0.34178     0.719816   0.0107913  0.159601    0.386026

julia> st[:c]

╭─────────────────────────────────╮
│ 6-element DimArray{Float64,1} c │
├─────────────────────────────────┴───────────────────────── dims ┐
  ↓ Y Sampled{Float64} 5.0:1.0:10.0 ForwardOrdered Regular Points
└─────────────────────────────────────────────────────────────────┘
  5.0  0.302061
  6.0  0.907197
  7.0  0.533709
  8.0  0.0477714
  9.0  0.780696
 10.0  0.0580864

Array-like indexing

Indexing with a scalar returns a NamedTuple of values, one for each layer:

julia> st[X=1, Y=4]

(a = 0.11558619369594669, b = 0.6096520588603549, c = 0.04777136223903122, d = 0.18560567159969743)

Reducing functions

Base functions like mean, maximum, reverse are applied to all layers of the stack.

julia> maximum(st)

(a = 0.9870264771655102, b = 0.9854976306334307, c = 0.9071972743780237, d = 0.8512258393553357)

julia> maximum(st; dims=Y)

╭───────────────╮
│ 10×1 DimStack │
├───────────────┴──────────────────────────────────────────── dims ┐
  ↓ X Sampled{Float64} 1.0:1.0:10.0 ForwardOrdered Regular Points,
  → Y Sampled{Float64} 7.5:6.0:7.5 ForwardOrdered Regular Points
├────────────────────────────────────────────────────────── layers ┤
  :a eltype: Float64 dims: X, Y size: 10×1
  :b eltype: Float64 dims: X, Y size: 10×1
  :c eltype: Float64 dims: Y size: 1
  :d eltype: Float64 dims: X size: 10
└──────────────────────────────────────────────────────────────────┘

broadcast_dims broadcasts functions over any mix of AbstractDimStack and AbstractDimArray returning a new AbstractDimStack with layers the size of the largest layer in the broadcast. This will work even if dimension permutation does not match in the objects.

Only atrix layers can be rotaed

julia> rotl90(st[(:a, :b)])

╭───────────────╮
│ 6×10 DimStack │
├───────────────┴───────────────────────────────────────────── dims ┐
  ↓ Y Sampled{Float64} 10.0:-1.0:5.0 ReverseOrdered Regular Points,
  → X Sampled{Float64} 1.0:1.0:10.0 ForwardOrdered Regular Points
├─────────────────────────────────────────────────────────── layers ┤
  :a eltype: Float64 dims: Y, X size: 6×10
  :b eltype: Float64 dims: Y, X size: 6×10
└───────────────────────────────────────────────────────────────────┘

julia> rotl90(st[(:a, :b)], 2)

╭───────────────╮
│ 10×6 DimStack │
├───────────────┴───────────────────────────────────────────── dims ┐
  ↓ X Sampled{Float64} 10.0:-1.0:1.0 ReverseOrdered Regular Points,
  → Y Sampled{Float64} 10.0:-1.0:5.0 ReverseOrdered Regular Points
├─────────────────────────────────────────────────────────── layers ┤
  :a eltype: Float64 dims: X, Y size: 10×6
  :b eltype: Float64 dims: X, Y size: 10×6
└───────────────────────────────────────────────────────────────────┘

Performance

Indexing stack is fast - indexing a single value return a NamedTuple from all layers is usally measures in nanoseconds, and no slower than manually indexing into each parent array directly.

There are some compilation overheads to this though, and stacks with very many layers can take a long time to compile.

julia> using BenchmarkTools

julia> @btime $st[X=1, Y=4]

  4.027 ns (0 allocations: 0 bytes)
(a = 0.11558619369594669, b = 0.6096520588603549, c = 0.04777136223903122, d = 0.18560567159969743)

julia> @btime $st[1, 4]

  4.839 ns (0 allocations: 0 bytes)
(a = 0.11558619369594669, b = 0.6096520588603549, c = 0.04777136223903122, d = 0.18560567159969743)