DimArrays
DimArray
s 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.909575 0.0995355 0.524798 0.787998 … 0.865795 0.432347 0.483378
0.638979 0.298515 0.244302 0.370195 0.227923 0.846243 0.438832
0.830109 0.378639 0.604399 0.136466 0.443772 0.811328 0.974362
0.85316 0.354549 0.00769058 0.756676 0.615184 0.300345 0.306298
0.592964 0.326327 0.745619 0.158275 0.0836401 0.0370274 0.44405
julia> da = DimArray(A, (X, Y))
╭──────────────────────────╮
│ 5×10 DimArray{Float64,2} │
├──────────────────── dims ┤
↓ X, → Y
└──────────────────────────┘
0.909575 0.0995355 0.524798 0.787998 … 0.865795 0.432347 0.483378
0.638979 0.298515 0.244302 0.370195 0.227923 0.846243 0.438832
0.830109 0.378639 0.604399 0.136466 0.443772 0.811328 0.974362
0.85316 0.354549 0.00769058 0.756676 0.615184 0.300345 0.306298
0.592964 0.326327 0.745619 0.158275 0.0836401 0.0370274 0.44405
We can access a value with the same dimension wrappers:
julia> da[Y(1), X(2)]
0.6389787609491319
There are shortcuts for creating DimArray
:
julia> A = rand(5, 10)
5×10 Matrix{Float64}:
0.54872 0.996542 0.230609 0.390031 … 0.571944 0.959871 0.0533506
0.0957938 0.465743 0.556614 0.505077 0.398391 0.0107543 0.421841
0.0208539 0.78142 0.542632 0.513765 0.623906 0.962773 0.633776
0.456424 0.580449 0.978976 0.82122 0.430993 0.151774 0.104433
0.476877 0.0419843 0.316208 0.883665 0.48284 0.29514 0.498707
julia> DimArray(A, (X, Y))
╭──────────────────────────╮
│ 5×10 DimArray{Float64,2} │
├──────────────────── dims ┤
↓ X, → Y
└──────────────────────────┘
0.54872 0.996542 0.230609 0.390031 … 0.571944 0.959871 0.0533506
0.0957938 0.465743 0.556614 0.505077 0.398391 0.0107543 0.421841
0.0208539 0.78142 0.542632 0.513765 0.623906 0.962773 0.633776
0.456424 0.580449 0.978976 0.82122 0.430993 0.151774 0.104433
0.476877 0.0419843 0.316208 0.883665 0.48284 0.29514 0.498707
julia> DimArray(A, (X, Y); name=:DimArray, metadata=Dict())
╭───────────────────────────────────╮
│ 5×10 DimArray{Float64,2} DimArray │
├───────────────────────────── dims ┤
↓ X, → Y
├───────────────────────── metadata ┤
Dict{Any, Any}()
└───────────────────────────────────┘
0.54872 0.996542 0.230609 0.390031 … 0.571944 0.959871 0.0533506
0.0957938 0.465743 0.556614 0.505077 0.398391 0.0107543 0.421841
0.0208539 0.78142 0.542632 0.513765 0.623906 0.962773 0.633776
0.456424 0.580449 0.978976 0.82122 0.430993 0.151774 0.104433
0.476877 0.0419843 0.316208 0.883665 0.48284 0.29514 0.498707
Constructing DimArray with arbitrary dimension names
For arbitrary names, we can use the Dim{:name}
dims by using Symbol
s, and indexing with keywords:
julia> da1 = DimArray(rand(5, 5), (:a, :b))
╭─────────────────────────╮
│ 5×5 DimArray{Float64,2} │
├─────────────────── dims ┤
↓ a, → b
└─────────────────────────┘
0.262991 0.740562 0.632142 0.82404 0.697234
0.134083 0.937061 0.289571 0.0277025 0.957323
0.100673 0.724124 0.715315 0.0581893 0.914827
0.919615 0.275814 0.985705 0.285206 0.62891
0.0844217 0.74372 0.776334 0.670626 0.40253
and get a value, here another smaller DimArray
:
julia> da1[a=3, b=1:3]
╭───────────────────────────────╮
│ 3-element DimArray{Float64,1} │
├───────────────────────── dims ┤
↓ b
└───────────────────────────────┘
0.100673
0.724124
0.715315
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.357396 0.962814 0.322783 0.925012 0.66514 0.130455 0.268434
0.111046 0.632161 0.104051 0.843069 0.938791 0.824398 0.788206
0.352453 0.760728 0.390524 0.485761 0.485116 0.366588 0.354733
0.50316 0.531275 0.126438 0.252417 0.107503 0.817248 0.0941785
0.636493 0.892905 0.362342 0.229889 0.510294 0.442488 0.697251
0.145047 0.224682 0.196309 0.0304519 0.983184 0.364253 0.058038
0.744177 0.0803948 0.304276 0.699686 0.175645 0.425852 0.316529
0.17307 0.951586 0.70994 0.861808 0.675527 0.238137 0.78033
0.58801 0.656822 0.8473 0.857947 0.0808685 0.336523 0.665203
0.10612 0.363405 0.814888 0.973441 0.342725 0.367211 0.734856
julia> da2[(X(3), Z(5))]
╭───────────────────────────────╮
│ 7-element DimArray{Float64,1} │
├───────────────────────── dims ┤
↓ Y
└───────────────────────────────┘
0.711485
0.781863
0.24496
0.940118
0.516642
0.980011
0.810662
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), (7, 4), (8, 2)] ↓ X, → Z
└──────────────────────────────────────────────────────────────────────────┘
(3, 5) (7, 4) (8, 2)
0.711485 0.941892 0.888661
0.781863 0.255105 0.989828
0.24496 0.786983 0.227465
0.940118 0.340949 0.0777192
0.516642 0.593784 0.47864
0.980011 0.500339 0.838781
0.810662 0.575002 0.392807
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.322783 0.767598 0.955895 0.0792387 0.341152
0.104051 0.143819 0.0729637 0.96008 0.758048
0.390524 0.580717 0.131455 0.607851 0.24496
0.126438 0.0113155 0.572203 0.54805 0.383359
0.362342 0.682069 0.0946191 0.882541 0.69934
0.196309 0.171503 0.781221 0.629026 0.259345
0.304276 0.466413 0.10197 0.786983 0.869642
0.70994 0.227465 0.933851 0.419538 0.296373
0.8473 0.933646 0.439049 0.588223 0.209677
0.814888 0.287489 0.829637 0.0774498 0.5674
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
julia> da1[X=Begin+1, Y=End]
┌ Warning: (X, Y) dims were not found in object.
└ @ DimensionalData.Dimensions ~/work/DimensionalData.jl/DimensionalData.jl/src/Dimensions/primitives.jl:777
╭─────────────────────────╮
│ 5×5 DimArray{Float64,2} │
├─────────────────── dims ┤
↓ a, → b
└─────────────────────────┘
0.262991 0.740562 0.632142 0.82404 0.697234
0.134083 0.937061 0.289571 0.0277025 0.957323
0.100673 0.724124 0.715315 0.0581893 0.914827
0.919615 0.275814 0.985705 0.285206 0.62891
0.0844217 0.74372 0.776334 0.670626 0.40253
It also works in ranges, even with basic math:
julia> da1[X=Begin:Begin+1, Y=Begin+1:End-1]
┌ Warning: (X, Y) dims were not found in object.
└ @ DimensionalData.Dimensions ~/work/DimensionalData.jl/DimensionalData.jl/src/Dimensions/primitives.jl:777
╭─────────────────────────╮
│ 5×5 DimArray{Float64,2} │
├─────────────────── dims ┤
↓ a, → b
└─────────────────────────┘
0.262991 0.740562 0.632142 0.82404 0.697234
0.134083 0.937061 0.289571 0.0277025 0.957323
0.100673 0.724124 0.715315 0.0581893 0.914827
0.919615 0.275814 0.985705 0.285206 0.62891
0.0844217 0.74372 0.776334 0.670626 0.40253
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
.
Indexing
Indexing AbstractDimArray
s works with getindex
, setindex!
and view
. The result is still an AbstracDimArray
, unless using all single Int
or Selector
s 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.620429 0.346726 0.165137 0.599303
0.509113 0.409966 0.794461 0.687485
0.886109 0.230697 0.375551 0.962826
julia> sum(da5; dims=Ti)
╭───────────────────────────╮
│ 3×4×1 DimArray{Float64,3} │
├───────────────────── dims ┤
↓ X, → Y, ↗ Ti
└───────────────────────────┘
[:, :, 1]
2.65791 2.88723 2.02691 2.56805
2.60399 2.10192 3.25853 2.25049
2.91367 2.91555 2.71291 3.71446
Dims keywords
Methods where dims, dim types, or Symbol
s 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 Dimension
s 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.
Range (min … max): 2.785 ns … 23.393 ns ┊ GC (min … max): 0.00% … 0.00%
Time (median): 2.795 ns ┊ GC (median): 0.00%
Time (mean ± σ): 2.808 ns ± 0.336 ns ┊ GC (mean ± σ): 0.00% ± 0.00%
▅▃ █▆ ▄ ▂ ▂ ▁ ▁
██▁▁▁▁▁▁▁▁▁▁▁▁██▁▁▁▁▁▁▁▁▁▁▁▁█▁█▁▁▁▁▁▁▁▁▁▁▁▁██▁▁▁▁▁▁▁▁▁▁▁▁█ █
2.78 ns Histogram: log(frequency) by time 2.82 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.
Range (min … max): 2.785 ns … 19.497 ns ┊ GC (min … max): 0.00% … 0.00%
Time (median): 2.795 ns ┊ GC (median): 0.00%
Time (mean ± σ): 2.804 ns ± 0.318 ns ┊ GC (mean ± σ): 0.00% ± 0.00%
▆▄ █ ▆ ▂ ▂ ▁
██▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█▁█▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█▁█▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█▇ █
2.78 ns Histogram: log(frequency) by time 2.82 ns <
Memory estimate: 0 bytes, allocs estimate: 0.