DimArrays

DimArrays are wrappers for other kinds of AbstractArray that add named dimension lookups.

Here we define a Matrix of Float64, and give it X and Y dimensions

julia> using DimensionalData

julia> A = rand(5, 10)

5×10 Matrix{Float64}:
 0.934419   0.176197  0.675467  0.208384  …  0.273986  0.509231   0.299799
 0.677974   0.468066  0.347379  0.541438     0.385262  0.52496    0.468184
 0.0599255  0.247198  0.813229  0.391395     0.208542  0.750146   0.106224
 0.557369   0.261741  0.44104   0.178902     0.561365  0.475747   0.264242
 0.104867   0.497181  0.570254  0.906883     0.986207  0.0287126  0.108968

julia> da = DimArray(A, (X, Y))

┌ 5×10 DimArray{Float64, 2} ┐
├───────────────────── dims ┤
  ↓ X, → Y
└───────────────────────────┘
 0.934419   0.176197  0.675467  0.208384  …  0.273986  0.509231   0.299799
 0.677974   0.468066  0.347379  0.541438     0.385262  0.52496    0.468184
 0.0599255  0.247198  0.813229  0.391395     0.208542  0.750146   0.106224
 0.557369   0.261741  0.44104   0.178902     0.561365  0.475747   0.264242
 0.104867   0.497181  0.570254  0.906883     0.986207  0.0287126  0.108968

We can access a value with the same dimension wrappers:

julia> da[Y(1), X(2)]

0.6779740716555893

There are shortcuts for creating DimArray:

julia> A = rand(5, 10)

5×10 Matrix{Float64}:
 0.601474  0.337576  0.770316  0.21149    …  0.532522  0.754787   0.999816
 0.113873  0.511078  0.201362  0.716257      0.864245  0.0874616  0.571281
 0.910981  0.503823  0.488029  0.0130048     0.841899  0.622239   0.585057
 0.436293  0.789198  0.32806   0.361921      0.669047  0.0802459  0.996398
 0.426888  0.46788   0.724709  0.15163       0.970273  0.869071   0.845226

julia> DimArray(A, (X, Y))

┌ 5×10 DimArray{Float64, 2} ┐
├───────────────────── dims ┤
  ↓ X, → Y
└───────────────────────────┘
 0.601474  0.337576  0.770316  0.21149    …  0.532522  0.754787   0.999816
 0.113873  0.511078  0.201362  0.716257      0.864245  0.0874616  0.571281
 0.910981  0.503823  0.488029  0.0130048     0.841899  0.622239   0.585057
 0.436293  0.789198  0.32806   0.361921      0.669047  0.0802459  0.996398
 0.426888  0.46788   0.724709  0.15163       0.970273  0.869071   0.845226

julia> DimArray(A, (X, Y); name=:DimArray, metadata=Dict())

┌ 5×10 DimArray{Float64, 2} DimArray ┐
├────────────────────────────── dims ┤
  ↓ X, → Y
└────────────────────────────────────┘
 0.601474  0.337576  0.770316  0.21149    …  0.532522  0.754787   0.999816
 0.113873  0.511078  0.201362  0.716257      0.864245  0.0874616  0.571281
 0.910981  0.503823  0.488029  0.0130048     0.841899  0.622239   0.585057
 0.436293  0.789198  0.32806   0.361921      0.669047  0.0802459  0.996398
 0.426888  0.46788   0.724709  0.15163       0.970273  0.869071   0.845226

Constructing DimArray with arbitrary dimension names

For arbitrary names, we can use the Dim{:name} dims by using Symbols, and indexing with keywords:

julia> da1 = DimArray(rand(5, 5), (:a, :b))

┌ 5×5 DimArray{Float64, 2} ┐
├──────────────────── dims ┤
  ↓ a, → b
└──────────────────────────┘
 0.0987741  0.798934  0.959907  0.146259  0.0726015
 0.848841   0.829194  0.877295  0.395143  0.55884
 0.0851053  0.972201  0.893793  0.537364  0.858332
 0.732574   0.453674  0.337006  0.819533  0.870536
 0.385228   0.199504  0.251766  0.733034  0.805351

and get a value, here another smaller DimArray:

julia> da1[a=3, b=1:3]

┌ 3-element DimArray{Float64, 1} ┐
├────────────────────────── dims ┤
  ↓ b
└────────────────────────────────┘
 0.0851053
 0.972201
 0.893793

Dimensional Indexing

When used for indexing, dimension wrappers free us from knowing the order of our objects axes. These are the same:

julia> da[X(2), Y(1)] == da[Y(1), X(2)]

true

We also can use Tuples of dimensions, like CartesianIndex, but they don't have to be in order of consecutive axes.

julia> da2 = rand(X(10), Y(7), Z(5))

┌ 10×7×5 DimArray{Float64, 3} ┐
├─────────────────────── dims ┤
  ↓ X, → Y, ↗ Z
└─────────────────────────────┘
[:, :, 1]
 0.722921   0.13252    0.551444   0.256885    0.336687   0.429353   0.471395
 0.578825   0.831918   0.692047   0.260515    0.271046   0.291887   0.462269
 0.122918   0.915793   0.0153506  0.374094    0.735257   0.0563844  0.292723
 0.0432075  0.95494    0.0692738  0.0345702   0.0513431  0.621854   0.0550672
 0.260182   0.519136   0.529282   0.126806    0.085903   0.0899993  0.430523
 0.888027   0.0766932  0.75284    0.377131    0.660382   0.477486   0.0301199
 0.906864   0.63899    0.528229   0.994505    0.200907   0.271974   0.524567
 0.91711    0.832814   0.865442   0.415242    0.379606   0.880918   0.19272
 0.462081   0.399758   0.0638113  0.728506    0.16874    0.635569   0.273725
 0.586116   0.666133   0.308111   0.00162234  0.864297   0.233014   0.209449

julia> da2[(X(3), Z(5))]

┌ 7-element DimArray{Float64, 1} ┐
├────────────────────────── dims ┤
  ↓ Y
└────────────────────────────────┘
 0.155799
 0.0613187
 0.768638
 0.950023
 0.102788
 0.597056
 0.434608

We can index with Vector of Tuple{Vararg(Dimension}} like vectors of CartesianIndex. This will merge the dimensions in the tuples:

julia> inds = [(X(3), Z(5)), (X(7), Z(4)), (X(8), Z(2))]

3-element Vector{Tuple{X{Int64}, Z{Int64}}}:
 (↓ X 3, → Z 5)
 (↓ X 7, → Z 4)
 (↓ X 8, → Z 2)

julia> da2[inds]

┌ 7×3 DimArray{Float64, 2} ┐
├──────────────────────────┴─────────────────────────────────────── dims ┐
  ↓ Y,
  → XZ MergedLookup{Tuple{Int64, Int64}} [(3, 5), …, (8, 2)] ↓ X, → Z
└────────────────────────────────────────────────────────────────────────┘
  (3, 5)     (7, 4)    (8, 2)
 0.155799   0.356991  0.35862
 0.0613187  0.923011  0.653142
 0.768638   0.682481  0.121614
 0.950023   0.650299  0.819897
 0.102788   0.866555  0.413731
 0.597056   0.455153  0.351141
 0.434608   0.179801  0.784166

DimIndices can be used like CartesianIndices but again, without the constraint of consecutive dimensions or known order.

julia> da2[DimIndices(dims(da2, (X, Z))), Y(3)]

┌ 10×5 DimArray{Float64, 2} ┐
├───────────────────── dims ┤
  ↓ X, → Z
└───────────────────────────┘
 0.551444   0.536081    0.37213    0.83849   0.8721
 0.692047   0.85907     0.115317   0.364995  0.79
 0.0153506  0.230224    0.742909   0.593399  0.768638
 0.0692738  0.943191    0.0173621  0.72779   0.306476
 0.529282   0.354768    0.645154   0.384335  0.551049
 0.75284    0.21307     0.856906   0.734764  0.146661
 0.528229   0.00588683  0.231082   0.682481  0.55649
 0.865442   0.121614    0.229128   0.453723  0.579951
 0.0638113  0.929518    0.147012   0.504668  0.493227
 0.308111   0.0155418   0.0474376  0.156663  0.973017

The Dimension indexing layer sits on top of regular indexing and can not be combined with it! Regular indexing specifies order, so doesn't mix well with our dimensions.

Mixing them will throw an error:

julia> da1[X(3), 4]

ERROR: ArgumentError: invalid index: X{Int64}(3) of type X{Int64}

Begin End indexing

WARNING

In base julia the keywords begin and end can be used to index the first or last element of an array. But this doesn't work when named indexing is used. Instead you can use the types Begin and End.

julia> da[X=Begin+1, Y=End]

0.4681839036255201

It also works in ranges, even with basic math:

julia> da[X=Begin:Begin+1, Y=Begin+1:End-1]

┌ 2×8 DimArray{Float64, 2} ┐
├──────────────────── dims ┤
  ↓ X, → Y
└──────────────────────────┘
 0.176197  0.675467  0.208384  0.438447  …  0.267014  0.273986  0.509231
 0.468066  0.347379  0.541438  0.71194      0.940686  0.385262  0.52496

Indexing

Indexing AbstractDimArrays works with getindex, setindex! and view. The result is still an AbstracDimArray, unless using all single Int or Selectors that resolve to Int inside Dimension.

dims keywords

In many Julia functions like, size or sum, you can specify the dimension along which to perform the operation as an Int. It is also possible to do this using Dimension types with AbstractDimArray:

julia> da5 = rand(X(3), Y(4), Ti(5))

┌ 3×4×5 DimArray{Float64, 3} ┐
├────────────────────── dims ┤
  ↓ X, → Y, ↗ Ti
└────────────────────────────┘
[:, :, 1]
 0.519517  0.0277465  0.322791  0.341342
 0.430873  0.905409   0.487639  0.274389
 0.861689  0.912467   0.67488   0.82837

julia> sum(da5; dims=Ti)

┌ 3×4×1 DimArray{Float64, 3} ┐
├────────────────────── dims ┤
  ↓ X, → Y, ↗ Ti
└────────────────────────────┘
[:, :, 1]
 3.36521  2.30918  2.35486  2.47951
 2.21246  2.67426  2.23088  1.82217
 3.34214  3.65988  2.75134  3.46547

Dims keywords

Methods where dims, dim types, or Symbols can be used to indicate the array dimension:

• size, axes, firstindex, lastindex

• cat, reverse, dropdims

• reduce, mapreduce

• sum, prod, maximum, minimum

• mean, median, extrema, std, var, cor, cov

• permutedims, adjoint, transpose, Transpose

• mapslices, eachslice

Performance

Indexing with Dimensions has no runtime cost. Let's benchmark it:

julia> using BenchmarkTools

julia> da4 = ones(X(3), Y(3))

┌ 3×3 DimArray{Float64, 2} ┐
├──────────────────── dims ┤
  ↓ X, → Y
└──────────────────────────┘
 1.0  1.0  1.0
 1.0  1.0  1.0
 1.0  1.0  1.0

julia> @benchmark $da4[X(1), Y(2)]

BenchmarkTools.Trial: 10000 samples with 1000 evaluations per sample.
 Range (min … max):  3.242 ns … 24.122 ns  ┊ GC (min … max): 0.00% … 0.00%
 Time  (median):     3.254 ns              ┊ GC (median):    0.00%
 Time  (mean ± σ):   3.298 ns ±  0.479 ns  ┊ GC (mean ± σ):  0.00% ± 0.00%

   ▁█▅                                                       
  ▃███▃▂▂▂▁▁▂▁▁▂▂▁▂▂▂▁▁▂▂▁▁▁▁▂▄▄▄▂▂▂▂▁▁▁▂▁▂▁▂▂▁▁▁▁▁▂▁▂▁▂▁▂▂▂ ▂
  3.24 ns        Histogram: frequency by time        3.48 ns <

 Memory estimate: 0 bytes, allocs estimate: 0.

the same as accessing the parent array directly:

julia> @benchmark parent($da4)[1, 2]

BenchmarkTools.Trial: 10000 samples with 1000 evaluations per sample.
 Range (min … max):  3.275 ns … 18.355 ns  ┊ GC (min … max): 0.00% … 0.00%
 Time  (median):     3.574 ns              ┊ GC (median):    0.00%
 Time  (mean ± σ):   3.602 ns ±  0.383 ns  ┊ GC (mean ± σ):  0.00% ± 0.00%

                                          ██              ▁▃ ▂
  ▅▄▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁████▁▇▆▁▁▃▄▁▁▃▁▁▁██ █
  3.28 ns      Histogram: log(frequency) by time      3.7 ns <

 Memory estimate: 0 bytes, allocs estimate: 0.