API

AbstractAxis{IdxMap}

Abstract supertype for axis metadata used by ComponentArray to map component names and shaped views onto positions in the wrapped array.

Type Parameters

• IdxMap: A static NamedTuple mapping component names to component indices or nested axis metadata. It is stored as a type parameter so generic indexing can resolve the map without per-instance storage.

Interface

Subtypes represent static component metadata. A subtype must use an IdxMap whose keys are the component names accepted by the axis and whose values are valid component indices, ranges, nested named tuples, or axis metadata supported by ComponentArray. The map must describe the same component layout for every instance of the subtype, and the subtype must be constructible without storing a second, runtime copy of the map.

The generic interface is derived from IdxMap; a subtype normally does not implement any methods itself:

• keys(axis) returns the component names in IdxMap order.
• axis[name] and axis[Val(name)] return a ComponentIndex for one named component.
• axis[names], where names is a tuple or array of symbols, returns one ComponentIndex whose indices are concatenated in the requested order.
• firstindex(axis) and lastindex(axis) describe the first and last flattened positions represented by the map.
• valkeys(axis) returns the same component names wrapped in Val objects for allocation-free generated indexing.

When an axis is passed to ComponentArray, its map must describe exactly the component positions in the supplied data, including any nested or shaped metadata. Define a custom subtype only when a distinct, statically known axis representation is required. Use Axis for ordinary named component layouts.

Examples

julia> using ComponentArrays

julia> struct TwoComponentAxis <: AbstractAxis{(left = 1, right = 2)} end

julia> ax = TwoComponentAxis();

julia> keys(ax)
(:left, :right)

ax = Axis(nt::NamedTuple)
ax = Axis(; kwargs...)
ax = Axis(symbols)

Construct static named-component metadata for a ComponentArray. The values in the mapping are one-based flat indices, ranges, nested named tuples, or other axis metadata. Use the keyword form for ordinary named layouts and the positional form when the complete mapping is already available as a NamedTuple.

Arguments

• nt: A NamedTuple mapping component names to flat indices or nested metadata.
• symbols: A tuple, vector, or varargs of Symbols. The symbols are assigned consecutive one-based indices.

Keywords

• kwargs...: Named component mappings. This is equivalent to Axis((; kwargs...)).

Returns

An Axis whose mapping is encoded in its type and therefore available to generic indexing without storing a runtime copy.

Examples

julia> using ComponentArrays

julia> ax = Axis(
           (
               a = 1, b = ViewAxis(2:7, PartitionedAxis(2, (a = 1, b = 2))),
               c = ViewAxis(8:10, (a = 1, b = 2:3)),
           )
       );

julia> A = [100, 4, 1.3, 1, 1, 4.4, 0.4, 2, 1, 45];

julia> ca = ComponentArray(A, ax)
ComponentVector{Float64}(a = 100.0, b = ComponentVector{Float64, SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, Tuple{Axis{(a = 1, b = 2)}}}[(a = 4.0, b = 1.3), (a = 1.0, b = 1.0), (a = 4.4, b = 0.4)], c = (a = 2.0, b = [1.0, 45.0]))

julia> ca.a
100.0

julia> ca.b
3-element LazyArray{ComponentVector{Float64, SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, Tuple{Axis{(a = 1, b = 2)}}}}:
 ComponentVector{Float64,SubArray...}(a = 4.0, b = 1.3)
 ComponentVector{Float64,SubArray...}(a = 1.0, b = 1.0)
 ComponentVector{Float64,SubArray...}(a = 4.4, b = 0.4)

julia> ca.c
ComponentVector{Float64,SubArray...}(a = 2.0, b = [1.0, 45.0])

julia> ca.c.b
2-element view(::Vector{Float64}, 9:10) with eltype Float64:
  1.0
 45.0

x = ComponentArray(nt::NamedTuple)
x = ComponentArray(; kwargs...)
x = ComponentArray(data::AbstractVector, ax)
x = ComponentArray{T}(args...; kwargs...) where {T}

Array type that can be accessed like an arbitrary nested mutable struct.

The component layout is stored in the axes field and the flat backing storage is stored in the data field. Component access through properties, symbols, and Val values is translated into indexing operations on data.

Type Parameters

• T: Element type of the backing array.
• N: Number of dimensions of the backing array.
• A: Concrete backing-array type.
• Axes: Tuple of AbstractAxis values, one per array dimension.

Fields

• data::A: The backing array containing the flattened component values.
• axes::Axes: The static component metadata used for named and nested indexing.

Arguments

• nt::NamedTuple or AbstractDict: Nested component values from which both the backing array and axes are inferred.
• data: An array containing the values to wrap.
• ax: One axis per dimension of data; use Axis, FlatAxis, or another AbstractAxis implementation.
• ComponentArray{T}: Convert inferred or supplied values to element type T.

Keywords

• kwargs...: Named component values, equivalent to passing a NamedTuple.

Returns

A ComponentArray that preserves the supplied backing storage and component metadata. Construction from a PartitionedAxis returns a lazy array of component arrays.

Throws

DimensionMismatch when a ComponentVector or ComponentMatrix alias receives an array with the wrong number of dimensions.

Examples

julia> using ComponentArrays

julia> x = ComponentArray(a = 1, b = [2, 1, 4], c = (a = 2, b = [1, 2]))
ComponentVector{Int64}(a = 1, b = [2, 1, 4], c = (a = 2, b = [1, 2]))

julia> x.c.a = 400;
       x
ComponentVector{Int64}(a = 1, b = [2, 1, 4], c = (a = 400, b = [1, 2]))

julia> x[5]
400

julia> collect(x)
7-element Vector{Int64}:
   1
   2
   1
   4
 400
   1
   2

x = ComponentMatrix(data::AbstractMatrix, ax...)
x = ComponentMatrix{T}(data::AbstractMatrix, ax...) where {T}

A ComponentMatrix is an alias for a two-dimensional ComponentArray.

Arguments

• data: A two-dimensional backing array.
• ax...: One axis per matrix dimension.
• T: Optional element type used by the undef constructor.

Returns

A two-dimensional ComponentArray with component-aware indexing.

Throws

DimensionMismatch if direct array input is not two-dimensional.

Examples

julia> using ComponentArrays

julia> x = ComponentMatrix(reshape(1:4, 2, 2), FlatAxis(), FlatAxis());

julia> size(x)
(2, 2)

x = ComponentVector(nt::NamedTuple)
x = ComponentVector(; kwargs...)
x = ComponentVector(data::AbstractVector, ax)
x = ComponentVector{T}(args...; kwargs...) where {T}

A ComponentVector is an alias for a one-dimensional ComponentArray.

Arguments

• nt, data, and ax: The same inputs accepted by ComponentArray, with data required to be one-dimensional when supplied directly.

Returns

A one-dimensional ComponentArray with component-aware indexing.

Throws

DimensionMismatch if direct array input is not one-dimensional.

Examples

julia> using ComponentArrays

julia> x = ComponentVector(a = 1, b = 2)
ComponentVector{Int64}(a = 1, b = 2)

julia> size(x)
(2,)

FlatAxis()

Axis marker for an unnamed, flat dimension of a ComponentArray.

FlatAxis carries no named components. It is useful for a dimension that should retain ordinary array indexing while other dimensions carry component names.

Examples

julia> using ComponentArrays

julia> x = ComponentArray(reshape(1:4, 2, 2), Axis(row = 1:2), FlatAxis());

julia> getaxes(x)
(Axis(row = 1:2,), FlatAxis())

KeepIndex(idx)

Wrap an index so indexing a ComponentArray retains component metadata for the selected entries. Use KeepIndex when a symbolic, integer, or range lookup should return a ComponentArray instead of a plain array or scalar.

Arguments

• idx: A component name, flat index, range, or : accepted by ComponentArray indexing. Integer indices are converted to a one-element range.

Returns

A KeepIndex wrapper consumed by getindex; it is not itself an array index.

Examples

julia> using ComponentArrays

julia> x = ComponentArray(a = 1, b = [2, 3]);

julia> kept = x[KeepIndex(:b)];

julia> keys(kept)
(:b,)

LazyArray(gen::Base.Generator)

Wrapper around Base.Generator that also indexes like an array. This is needed to make ComponentArrays that hold arrays of ComponentArrays

PartitionedAxis(partition_size, index_map)

Axis metadata for a homogeneous array of component layouts. Constructing a ComponentArray with a PartitionedAxis produces a lazy array whose entries are ComponentArrays sharing the same component map.

Arguments

• partition_size: Number of flat data elements in each component layout.
• index_map: A NamedTuple or AbstractAxis describing one layout.

Fields

• ax: The axis representing one component layout. Its map is also encoded in the IdxMap type parameter.

Returns

A PartitionedAxis whose size is partition_size. When used in a ComponentArray constructor, the corresponding dimension is partitioned into lazy component arrays.

Examples

julia> using ComponentArrays

julia> axis = PartitionedAxis(2, (x = 1, y = 2));

julia> size(axis)
2

Shaped1DAxis(shape::Tuple{<:Integer})

Axis marker for a one-dimensional array component. ShapedAxis((n,)) returns a Shaped1DAxis so vector-valued components keep their one-dimensional shape.

Returns

An axis whose size is the supplied one-dimensional shape and whose flattened length is the sole shape entry.

Examples

julia> using ComponentArrays

julia> ax = Shaped1DAxis((3,));

julia> size(ax)
(3,)

ShapedAxis(shape::Tuple{Vararg{Integer}})

Axis metadata that preserves the shape of a multidimensional component stored in a flat ComponentArray data buffer.

Arguments

• shape: The dimensions of the component. A one-dimensional shape produces a Shaped1DAxis instead.

Returns

An axis whose size is shape. For a one-dimensional shape, the constructor returns a Shaped1DAxis instead.

Examples

julia> using ComponentArrays

julia> size(ShapedAxis((2, 3)))
(2, 3)

ViewAxis(parent_index, index_map)

Axis metadata that maps a component layout onto parent_index in its parent array. ViewAxis preserves nested component names while recording the parent positions used to retrieve the component. For flat and null axes it simplifies to the bare index.

Arguments

• parent_index: Indices of the component in the parent array.
• index_map: A NamedTuple or AbstractAxis describing the component layout.

Fields

• ax: The nested axis used to interpret the selected parent positions.

Returns

A ViewAxis that exposes index_map through the positions in parent_index. When the map is flat or null, the constructor returns the bare parent index instead.

Examples

julia> using ComponentArrays

julia> axis = ViewAxis(2:3, (x = 1, y = 2));

julia> keys(axis)
(:x, :y)

fastindices(i...)
fastindices(i::Tuple)

Deprecated helper for converting symbolic indices to Val wrappers. Use Val constructors directly instead.

Arguments

• i...: Symbols or other values accepted by Val.

Returns

A tuple of Val wrappers. The tuple form and varargs form are equivalent.

This function emits a deprecation warning; call Val.(...) directly in new code.

Examples

Val.((:a, :b))

getaxes(x::ComponentArray)

Access .axes field of a ComponentArray. This is different than axes(x::ComponentArray), which returns the axes of the contained array.

Arguments

• x: A ComponentArray, an adjoint/transpose of one, a tuple of axes, or a type carrying component-axis metadata.

Returns

The component-axis metadata associated with x, represented as a tuple of axes.

Examples

julia> using ComponentArrays

julia> ax = Axis(a = 1:3, b = (4:6, (a = 1, b = 2:3)))
Axis(a = 1:3, b = (4:6, (a = 1, b = 2:3)))

julia> A = zeros(6, 6);

julia> ca = ComponentArray(A, (ax, ax))
6×6 ComponentMatrix{Float64} with axes Axis(a = 1:3, b = (4:6, (a = 1, b = 2:3))) × Axis(a = 1:3, b = (4:6, (a = 1, b = 2:3)))
 0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0

julia> getaxes(ca)
(Axis(a = 1:3, b = (4:6, (a = 1, b = 2:3))), Axis(a = 1:3, b = (4:6, (a = 1, b = 2:3))))

getdata(x::ComponentArray)

Return the backing array of a ComponentArray. For ordinary arrays and scalars, getdata returns its argument unchanged; this makes generic code work with both wrapped and unwrapped values.

Arguments

• x: A ComponentArray, an adjoint/transpose of one, or an ordinary value.

Returns

The ordinary backing value associated with x. For an ordinary value, returns x unchanged.

Examples

julia> using ComponentArrays

julia> x = ComponentArray(a = 1, b = [2, 3]);

julia> getdata(x)
3-element Vector{Int64}:
 1
 2
 3

label2index(x::ComponentVector, str::AbstractString)
label2index(label_array, str::AbstractString)

Convert labels made by labels function to an array of flat indices of a ComponentVector.

Arguments

• x: A ComponentVector or a vector of labels returned by labels.
• str: A complete or prefix label to look up.

Returns

A vector of flat indices matching str. Prefix matches include all nested component positions below that label.

Examples

julia> x = ComponentArray(a = 5, b = [(a = (a = 20, b = 1), b = 0), (a = (a = 33, b = 1), b = 0)],
           c = (a = (a = 2, b = [1, 2]), b = [1.0 2.0; 5 6]))
ComponentVector{Float64}(a = 5.0, b = ComponentVector{Float64, SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, Tuple{Axis{(a = ViewAxis(1:2, Axis(a = 1, b = 2)), b = 3)}}}[(a = (a = 20.0, b = 1.0), b = 0.0), (a = (a = 33.0, b = 1.0), b = 0.0)], c = (a = (a = 2.0, b = [1.0, 2.0]), b = [1.0 2.0; 5.0 6.0]))

julia> ComponentArrays.labels(x)
14-element Vector{String}:
 "a"
 "b[1].a.a"
 "b[1].a.b"
 "b[1].b"
 "b[2].a.a"
 "b[2].a.b"
 "b[2].b"
 "c.a.a"
 "c.a.b[1]"
 "c.a.b[2]"
 "c.b[1,1]"
 "c.b[2,1]"
 "c.b[1,2]"
 "c.b[2,2]"

julia> ComponentArrays.label2index(x, "c.a")
3-element Vector{Int64}:
  8
  9
 10

julia> ComponentArrays.label2index(x, "b[1]")
3-element Vector{Int64}:
 2
 3
 4

see also labels

labels(x::ComponentVector)

Get string labels for each index of a ComponentVector. Useful for automatic plot legend labelling.

Arguments

• x: A component array or nested component-array structure to label.

Returns

A vector of strings, one for each flattened component position. Nested fields use dot notation and array indices use bracket notation.

Examples

julia> x = ComponentArray(a = 5, b = [(a = (a = 20, b = 1), b = 0), (a = (a = 33, b = 1), b = 0)],
           c = (a = (a = 2, b = [1, 2]), b = [1.0 2.0; 5 6]))
ComponentVector{Float64}(a = 5.0, b = ComponentVector{Float64, SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, Tuple{Axis{(a = ViewAxis(1:2, Axis(a = 1, b = 2)), b = 3)}}}[(a = (a = 20.0, b = 1.0), b = 0.0), (a = (a = 33.0, b = 1.0), b = 0.0)], c = (a = (a = 2.0, b = [1.0, 2.0]), b = [1.0 2.0; 5.0 6.0]))

julia> ComponentArrays.labels(x)
14-element Vector{String}:
 "a"
 "b[1].a.a"
 "b[1].a.b"
 "b[1].b"
 "b[2].a.a"
 "b[2].a.b"
 "b[2].b"
 "c.a.a"
 "c.a.b[1]"
 "c.a.b[2]"
 "c.b[1,1]"
 "c.b[2,1]"
 "c.b[1,2]"
 "c.b[2,2]"

see also label2index

valkeys(x::ComponentVector)
valkeys(x::AbstractAxis)

Returns Val-wrapped keys of ComponentVector for fast iteration over component keys. Also works directly on an AbstractAxis.

Arguments

• x: A ComponentVector or AbstractAxis.

Returns

A tuple of Val objects in the same order as keys(x).

Examples

julia> using ComponentArrays

julia> ca = ComponentArray(a = 1, b = [1, 2, 3], c = (a = 4,))
ComponentVector{Int64}(a = 1, b = [1, 2, 3], c = (a = 4))

julia> [ca[k] for k in valkeys(ca)]
3-element Vector{Any}:
 1
  [1, 2, 3]
  ComponentVector{Int64}(a = 4)

julia> sum(prod(ca[k]) for k in valkeys(ca))
11

@static_unpack lhs = rhs

Unpack fields from a ComponentVector, converting plain array fields to StaticArrays values when their sizes are known from the component axes. Scalar fields and nested ComponentArrays are returned unchanged.

Arguments

• lhs: One variable or a tuple of variables receiving the unpacked fields.
• rhs: A ComponentVector expression.

Returns

Assignments to the variables in lhs; plain array fields with static shapes become StaticArrays values.

Throws

An AssertionError if the left-hand side is not an assignment, or an ErrorException if the assignment target is not a symbol or tuple of symbols.

Examples

julia> using ComponentArrays, StaticArrays

julia> x = ComponentVector(a = 5, b = [4, 1]);

julia> @static_unpack a, b = x;

julia> a
5

julia> b
2-element SVector{2, Int64} with indices SOneTo(2):
 4
 1