LArrays

LArrays are fully mutable arrays with labels. There is no performance loss by using labelled indexing instead of purely numerical indexing. Using the macro with values and labels generates the labelled array with the given values:

Users interested in using labelled elements in their arrays should also consider ComponentArrays from the ComponentArrays.jl library. ComponentArrays are well integrated into the SciML ecosystem.

@LArray and @LVector macros

Macro constructors are convenient for building most LArray objects. An @LArray may be of arbitrary dimension while an @LVector is a one dimensional array.

LabelledArrays.@LArrayMacro
@LArray Eltype Size Names
@LArray Values Names

The @LArray macro creates an LArray with names determined from the Names vector and values determined from the Values vector. Otherwise, the eltype and size are used to make an LArray with undefined values.

A = @LArray [1,2,3] (:a,:b,:c)
A.a == 1

Users can also generate a labelled array with undefined values by instead giving the dimensions. This approach is useful if the user intends to pre-allocate an array for some later input.

A = @LArray Float64 (2,2) (:a,:b,:c,:d)
W = rand(2,2)
A .= W
A.d == W[2,2]

Users may also use an alternative constructor to set the Names and Values and ranges at the same time.

julia> z = @LArray [1.,2.,3.] (a = 1:2, b = 2:3);
julia> z.b
2-element view(::Array{Float64,1}, 2:3) with eltype Float64:
 2.0
 3.0

julia> z = @LArray [1 2; 3 4] (a = (2, :), b = 2:3);
julia> z.a
2-element view(::Array{Int64,2}, 2, :) with eltype Int64:
 3
 4

The labels of LArray and SLArray can be accessed by function symbols, which returns a tuple of symbols.

LabelledArrays.@LVectorMacro
@LVector Type Names

The @LVector macro creates an LArray of dimension 1 with eltype and undefined values. The vector's length is equal to the number of names given.

As with an LArray, the user can initialize the vector and set its values later.

A = @LVector Float64 (:a,:b,:c,:d)
A .= rand(4)

On the other hand, users can also initialize the vector and set its values at the same time:

b = @LVector [1,2,3] (:a,:b,:c)

LArray and LVector constructors

The original constructors for LArrays and LVectors are as follows:

LabelledArrays.LArrayType
LArray(::Tuple, ::NamedTuple)
LArray(::Tuple, kwargs)

The standard constructors for LArray.

For example:

LArray((2,2), (a=1, b=2, c=3, d=4))  # need to specify size
LArray((2,2); a=1, b=2, c=3, d=4)
LVector(v1::Union{SLArray,LArray}; kwargs...)

Creates a copy of v1 with corresponding items in kwargs replaced.

For example:

ABCD = @SLArray (2,2) (:a,:b,:c,:d);
B = ABCD(1,2,3,4);
B2 = LArray(B; c=30 )
LabelledArrays.LVectorFunction
LVector(::NamedTuple)
LVector(kwargs)

The standard constructor for LVector.

For example:

LVector((a=1, b=2))
LVector(a=1, b=2)
LVector(v1::Union{SLArray,LArray}; kwargs...)

Creates a 1D copy of v1 with corresponding items in kwargs replaced.

For example:

z = LVector(a=1, b=2, c=3);
z2 = LVector(z; c=30)

Manipulating LArrays and LVectors

User may want a list of the labels or keys in an LArray or LVector. The symbols(::LArray) function returns a tuple of array labels.

LabelledArrays.symbolsFunction
symbols(::SLArray)

Returns the labels of the SLArray .

For example:

julia> z = SLVector(a=1, b=2, c=3)
3-element SLArray{Tuple{3}, Int64, 1, 3, (:a, :b, :c)} with indices SOneTo(3):
 :a => 1
 :b => 2
 :c => 3

julia> symbols(z)
(:a, :b, :c)
symbols(::LArray)

Returns the labels of the LArray .

For example:

julia julia> z = @LVector Float64 (:a, :b, :c, :d); julia> symbols(z) (:a, :b, :c, :d)`