References

circular_pad(x; first_pad=0, last_pad=0, sym_pad=nothing)

The border elements wrap around. For instance, indexing beyond the left border returns values starting from the right border.

\[\boxed{ \begin{array}{l|c|r} c\, d\, e\, f & a \, b \, c \, d \, e \, f & a \, b \, c \, d \end{array} }\]

closest(collection, x)

Find the index of the value in collection closest to x.

is_dense_wrapper(::Type{T}) where {T} -> Bool

Do all the indices of T map to a unique indice of the parent data that is wrapped? This is not true for padded axes.

is_key([collection,] arg) -> Bool

Whether arg refers to a key of axis.

permuteddimsview(A, perm)

returns a "view" of A with its dimensions permuted as specified by perm. This is like permutedims, except that it produces a view rather than a copy of A; consequently, any manipulations you make to the output will be mirrored in A. Compared to the copy, the view is much faster to create, but generally slower to use.

reflect_pad(x; first_pad=0, last_pad=0, sym_pad=nothing)

The border elements reflect relative to the edge itself.

\[\boxed{ \begin{array}{l|c|r} d\, c\, b\, a & a \, b \, c \, d \, e \, f & f \, e \, d \, c \end{array} }\]

replicate_pad(x; first_pad=0, last_pad=0, sym_pad=nothing)

The border elements extend beyond the image boundaries.

\[\boxed{ \begin{array}{l|c|r} a\, a\, a\, a & a \, b \, c \, d \, e \, f & f \, f \, f \, f \end{array} }\]

struct_view(A)

Creates a MappedArray whose element type is derived from the first StructAxis found as an axis of A.

deleteat!(a::AxisVector, arg)

Remove the items corresponding to A[arg], and return the modified a. Subsequent items are shifted to fill the resulting gap. If the axis of a is an SimpleAxis then it is shortened to match the length of a.

Examples

julia> using AxisIndices

julia> x = AxisArray([1, 2, 3, 4]);

julia> deleteat!(x, 3)
3-element AxisArray(::Array{Int64,1}
  • axes:
     1 = 1:3
)
     1
  1  1
  2  2
  3  4  

julia> x = AxisArray([1, 2, 3, 4], ["a", "b", "c", "d"]);

julia> keys.(axes(deleteat!(x, "c")))
(["a", "b", "d"],)

inv(M::AxisMatrix)

Computes the inverse of an AxisMatrixMatrix

julia> using AxisIndices, LinearAlgebra

julia> M = AxisArray([2 5; 1 3], ["a", "b"], [:one, :two]);

julia> keys.(axes(inv(M)))
([:one, :two], ["a", "b"])

reshape(A::AxisArray, shape)

Reshape the array and axes of A.

Examples

julia> using AxisIndices

julia> A = reshape(AxisArray(Vector(1:8), [:a, :b, :c, :d, :e, :f, :g, :h]), 4, 2);

julia> axes(A)
(Axis([:a, :b, :c, :d] => SimpleAxis(1:4)), SimpleAxis(1:2))

julia> axes(reshape(A, 2, :))
(Axis([:a, :b] => SimpleAxis(1:2)), SimpleAxis(1:4))

rot180(A::AxisMatrix)

Rotate A 180 degrees, along with its axes keys.

Examples

julia> using AxisIndices

julia> a = AxisArray([1 2; 3 4], ["a", "b"], ["one", "two"]);

julia> b = rot180(a);

julia> keys.(axes(b))
(["b", "a"], ["two", "one"])

julia> c = rotr90(rotr90(a));

julia> keys.(axes(c))
(["b", "a"], ["two", "one"])

julia> a["a", "one"] == b["a", "one"] == c["a", "one"]
true

rotl90(A::AxisMatrix)

Rotate A left 90 degrees, along with its axes keys.

Examples

julia> using AxisIndices

julia> a = AxisArray([1 2; 3 4], ["a", "b"], ["one", "two"]);

julia> b = rotl90(a);

julia> keys.(axes(b))
(["two", "one"], ["a", "b"])

julia> a["a", "one"] == b["one", "a"]
true

rotr90(A::AxisMatrix)

Rotate A right 90 degrees, along with its axes keys.

Examples

julia> using AxisIndices

julia> a = AxisArray([1 2; 3 4], ["a", "b"], ["one", "two"]);

julia> b = rotr90(a);

julia> keys.(axes(b))
(["one", "two"], ["b", "a"])

julia> a["a", "one"] == b["one", "a"]
true

diag(M::AxisMatrix, k::Integer=0; dim::Val=Val(1))

The kth diagonal of an AxisMatrixMatrix, M. The keyword argument dim specifies which which dimension's axis to preserve, with the default being the first dimension. This can be change by specifying dim=Val(2) instead.

julia> using AxisIndices, LinearAlgebra

julia> A = AxisArray([1 2 3; 4 5 6; 7 8 9], ["a", "b", "c"], [:one, :two, :three]);

julia> keys.(axes(diag(A)))
(["a", "b", "c"],)

julia> keys.(axes(diag(A, 1; dim=Val(2))))
([:one, :two],)

lq(A::AxisArray, args...; kwargs...)

Compute the LQ factorization of an AxisArray A.

Examples

julia> using AxisIndices, LinearAlgebra

julia> m = AxisArray([1.0 2; 3 4], (2:3, 3:4));

julia> F = lq(m);

julia> axes(F.L)
(offset(1)(SimpleAxis(1:2)), SimpleAxis(1:2))

julia> axes(F.Q)
(SimpleAxis(1:2), offset(2)(SimpleAxis(1:2)))

julia> axes(F.L * F.Q)
(offset(1)(SimpleAxis(1:2)), offset(2)(SimpleAxis(1:2)))

lu(A::AxisArray, args...; kwargs...)

Compute the LU factorization of an AxisArray A.

Examples

julia> using AxisIndices, LinearAlgebra

julia> m = AxisArray([1.0 2; 3 4], (2:3, 3:4));

julia> F = lu(m);

julia> axes(F.L)
(offset(1)(SimpleAxis(1:2)), SimpleAxis(1:2))

julia> axes(F.U)
(SimpleAxis(1:2), offset(2)(SimpleAxis(1:2)))

julia> F.p
2-element Array{Int64,1}:
 3
 2

julia> axes(F.P)
(offset(1)(SimpleAxis(1:2)), offset(1)(SimpleAxis(1:2)))

julia> axes(F.P * m)
(offset(1)(SimpleAxis(1:2)), offset(2)(SimpleAxis(1:2)))

julia> axes(F.L * F.U)
(offset(1)(SimpleAxis(1:2)), offset(2)(SimpleAxis(1:2)))

qr(F::AxisArray, args...; kwargs...)

Compute the QR factorization of an AxisArray A.

Examples

julia> using AxisIndices, LinearAlgebra

julia> m = AxisArray([1.0 2; 3 4], (2:3, 3:4));

julia> F = qr(m, Val(true));

julia> axes(F.Q)
(offset(1)(SimpleAxis(1:2)), SimpleAxis(1:2))

julia> axes(F.R)
(SimpleAxis(1:2), offset(2)(SimpleAxis(1:2)))

julia> axes(F.Q * F.R)
(offset(1)(SimpleAxis(1:2)), offset(2)(SimpleAxis(1:2)))

julia> axes(F.p)
(Base.OneTo(2),)

julia> axes(F.P)
(offset(1)(SimpleAxis(1:2)), offset(1)(SimpleAxis(1:2)))

julia> axes(F.P * AxisArray([1.0 2; 3 4], (2:3, 3:4)))
(offset(1)(SimpleAxis(1:2)), offset(2)(SimpleAxis(1:2)))

svd(F::AxisArray, args...; kwargs...)

Compute the singular value decomposition (SVD) of an AxisArray A.

Examples

julia> using AxisIndices, LinearAlgebra

julia> m = AxisArray([1.0 2; 3 4], (2:3, 3:4));

julia> F = svd(m);

julia> axes(F.U)
(offset(1)(SimpleAxis(1:2)), SimpleAxis(1:2))

julia> axes(F.V)
(offset(2)(SimpleAxis(1:2)), SimpleAxis(1:2))

julia> axes(F.Vt)
(SimpleAxis(1:2), offset(2)(SimpleAxis(1:2)))

julia> axes(F.U * Diagonal(F.S) * F.Vt)
(offset(1)(SimpleAxis(1:2)), offset(2)(SimpleAxis(1:2)))

cor(x::AxisMatrix; dims=1, kwargs...)

Performs cor on the parent matrix of x and reconstructs a similar type with the appropriate axes.

Examples

julia> using AxisIndices, Statistics

julia> A = AxisArray([1 2 3; 4 5 6; 7 8 9], ["a", "b", "c"], [:one, :two, :three]);

julia> keys.(axes(cor(A, dims = 2)))
(["a", "b", "c"], ["a", "b", "c"])

julia> keys.(axes(cor(A, dims = 1)))
([:one, :two, :three], [:one, :two, :three])

cov(x::AxisMatrix; dims=1, kwargs...)

Performs cov on the parent matrix of x and reconstructs a similar type with the appropriate axes.

Examples

julia> using AxisIndices, Statistics

julia> A = AxisArray([1 2 3; 4 5 6; 7 8 9], ["a", "b", "c"], [:one, :two, :three]);

julia> keys.(axes(cov(A, dims = 2)))
(["a", "b", "c"], ["a", "b", "c"])

julia> keys.(axes(cov(A, dims = 1)))
([:one, :two, :three], [:one, :two, :three])

AbstractAxis

An AbstractVector subtype optimized for indexing.

AbstractOffsetAxis{I,Inds}

Supertype for axes that begin indexing offset from one. All subtypes of AbstractOffsetAxis use the keys for indexing and only convert to the underlying indices when to_index(::OffsetAxis, ::Integer) is called (i.e. when indexing the an array with an AbstractOffsetAxis. See OffsetAxis, CenteredAxis, and IdentityAxis for more details and examples.

Axis(k[, v=OneTo(length(k))])

Subtypes of AbstractAxis that maps keys to values. The first argument specifies the keys and the second specifies the values. If only one argument is specified then the values span from 1 to the length of k.

Examples

The value for all of these is the same.

julia> using AxisIndices

julia> x = Axis(2.0:11.0)  # when only one argument is specified assume it's the keys
Axis(2.0:1.0:11.0 => SimpleAxis(1:10))

julia> y = Axis(1:10)
Axis(1:10 => SimpleAxis(1:10))

Standard indexing returns the same values

julia> x[2]
2

julia> x[2] == y[2]
true

julia> x[1:2]
Axis(2.0:1.0:3.0 => SimpleAxis(1:2))

julia> y[1:2]
Axis(1:2 => SimpleAxis(1:2))

julia> x[1:2] == y[1:2]
true

Functions that return true or false may be used to search the keys for their corresponding index. The following is equivalent to the previous example.

julia> x[==(3.0)]
2

julia> x[3.0] ==  # 3.0 is the 2nd key of x
       y[==(2)]   # 2 is the 2nd key of z
true

julia> x[<(4.0)]  # all keys less than 4.0 are 2.0:3.0 which correspond to values 1:2
Axis(2.0:1.0:3.0 => SimpleAxis(1:2))

julia> y[<=(3.0)]  # all keys less than or equal to 3.0 are 2.0:3.0 which correspond to values 1:2
Axis(2.0:1.0:3.0 => SimpleAxis(1:2))

julia> z[<(3)]  # all keys less than or equal to 3 are 1:2 which correspond to values 1:2
Axis(1:2 => SimpleAxis(1:2))

julia> x[<(4.0)] == y[<=(3.0)] == z[<(3)]
true

Notice that == returns a single value instead of a collection of all elements where the key was found to be true. This is because all keys must be unique so there can only ever be one element returned.

AxisArray{T,N,P,AI}

An array struct that wraps any parent array and assigns it an AbstractAxis for each dimension. The first argument is the parent array and the second argument is a tuple of subtypes to AbstractAxis or keys that will be converted to subtypes of AbstractAxis with the provided keys.

AxisInitializer <: Function

Supertype for functions that assist in initialization of AbstractAxis subtypes.

AxisVector

A vector whose indices have keys.

Examples

julia> using AxisIndices

julia> AxisVector([1, 2], [:a, :b])
2-element AxisArray(::Array{Int64,1}
  • axes:
     1 = [:a, :b]
)
      1
  :a  1
  :b  2  

CartesianAxes

Alias for LinearIndices where indices are subtypes of AbstractAxis.

Examples

julia> using AxisIndices

julia> cartaxes = CartesianAxes((Axis(2.0:5.0), Axis(1:4)));

julia> cartinds = CartesianIndices((1:4, 1:4));

julia> cartaxes[2, 2]
CartesianIndex(2, 2)

julia> cartinds[2, 2]
CartesianIndex(2, 2)

center(collection, origin)
center(collection, origin)

Shortcut for creating CenteredAxis.

Examples

julia> using AxisIndices

julia> AxisArray(ones(3), center(0))
3-element AxisArray(::Array{Float64,1}
  • axes:
     1 = -1:1
)
      1
  -1  1.0
  0   1.0
  1   1.0

CenteredArray(A::AbstractArray)

Provides centered axes for indexing A.

Examples

julia> using AxisIndices

julia> AxisIndices.CenteredArray(ones(3,3))
3×3 AxisArray(::Array{Float64,2}
  • axes:
     1 = -1:1
     2 = -1:1
)
      -1    0    1
  -1   1.0  1.0  1.0
  0    1.0  1.0  1.0
  1    1.0  1.0  1.0

CenteredAxis(origin=0, indices)

A CenteredAxis takes indices and provides a user facing set of keys centered around zero. The CenteredAxis is a subtype of AbstractOffsetAxis and its keys are treated as the predominant indexing style. Note that the element type of a CenteredAxis cannot be unsigned because any instance with a length greater than 1 will begin at a negative value.

Examples

A CenteredAxis sends all indexing arguments to the keys and only maps to the indices when to_index is called.

julia> using AxisIndices

julia> axis = AxisIndices.CenteredAxis(1:10)
center(0)(SimpleAxis(1:10))

julia> axis[10]  # the indexing goes straight to keys and is centered around zero
ERROR: BoundsError: attempt to access center(0)(SimpleAxis(1:10)) at index [10]
[...]

julia> axis[-4]
-4

CenteredVector(v::AbstractVector)

Provides a centered axis for indexing v.

Examples

julia> using AxisIndices

julia> AxisIndices.CenteredVector(ones(3))
3-element AxisArray(::Array{Float64,1}
  • axes:
     1 = -1:1
)
      1
  -1  1.0
  0   1.0
  1   1.0

CenteredVector{T}(init::ArrayInitializer, sz::Integer)

Creates a vector with elements of type T of size sz and a centered axis.

Examples

julia> using AxisIndices

julia> AxisIndices.CenteredVector{Union{Missing, Int}}(missing, 3)
3-element AxisArray(::Array{Union{Missing, Int64},1}
  • axes:
     1 = -1:1
)
      1
  -1   missing
  0    missing
  1    missing

idaxis(inds::AbstractUnitRange{<:Integer})

Shortcut for creating IdentityAxis.

Examples

julia> using AxisIndices

julia> AxisArray(ones(3), idaxis)[2:3]
2-element AxisArray(::Array{Float64,1}
  • axes:
     1 = 2:3
)
     1
  2  1.0
  3  1.0

IdentityArray(A::AbstractArray)

Provides IdentityAxiss for indexing A.

Examples

julia> using AxisIndices

julia> AxisIndices.IdentityArray(ones(3,3))[2:3, 2:3]
2×2 AxisArray(::Array{Float64,2}
  • axes:
     1 = 2:3
     2 = 2:3
)
     2    3
  2  1.0  1.0
  3  1.0  1.0

IdentityAxis(start, stop) -> axis
IdentityAxis(keys::AbstractUnitRange) -> axis
IdentityAxis(keys::AbstractUnitRange, indices::AbstractUnitRange) -> axis

AbstractAxis subtype that preserves indices after indexing.

Examples

julia> using AxisIndices

julia> axis = AxisIndices.IdentityAxis(3:5)
idaxis(3:5)(SimpleAxis(1:3))

julia> axis[4:5]
idaxis(4:5)(SimpleAxis(2:3))

IdentityVector(v::AbstractVector)

Provides an IdentityAxis for indexing v.

Examples

julia> using AxisIndices

julia> AxisIndices.IdentityVector(ones(4))[3:4]
2-element AxisArray(::Array{Float64,1}
  • axes:
     1 = 3:4
)
     1
  3  1.0
  4  1.0

IdentityVector{T}(init::ArrayInitializer, sz::Integer)

Creates a vector with elements of type T of size sz an IdentityAxis.

Examples

julia> using AxisIndices

julia> AxisIndices.IdentityVector{Union{Missing, Int}}(missing, 3)[2:3]
2-element AxisArray(::Array{Union{Missing, Int64},1}
  • axes:
     1 = 2:3
)
     1
  2   missing
  3   missing

IndexAxis

Index style for mapping keys to an array's parent indices.

LinearAxes

Alias for LinearIndices where indices are subtypes of AbstractAxis.

Examples

julia> using AxisIndices

julia> linaxes = LinearAxes((Axis(2.0:5.0), Axis(1:4)));

julia> lininds = LinearIndices((1:4, 1:4));

julia> linaxes[2, 2]
6

julia> lininds[2, 2]
6

NamedAxisArray(parent::AbstractArray; kwargs...) = NamedAxisArray(parent, kwargs)
NamedAxisArray(parent::AbstractArray, axes::NamedTuple{L,AbstractAxes})

Type alias for NamedDimsArray whose parent array is an AxisArray. If key word arguments are provided then each key word becomes the name of a dimension and its assigned value is sent to the corresponding axis when constructing the underlying AxisArray.

Examples

julia> using AxisIndices

julia> A = NamedAxisArray{(:x, :y, :z)}(reshape(1:24, 2, 3, 4), ["a", "b"], ["one", "two", "three"], 2:5)
2×3×4 NamedDimsArray(AxisArray(reshape(::UnitRange{Int64}, 2, 3, 4)
  • axes:
     x = ["a", "b"]
     y = ["one", "two", "three"]
     z = 2:5
))
[:, :, 2] =
       "one"   "two"   "three"
  "a"  1       3       5
  "b"  2       4       6

[:, :, 3] =
       "one"   "two"    "three"
  "a"  7        9       11
  "b"  8       10       12

[:, :, 4] =
       "one"    "two"    "three"
  "a"  13       15       17
  "b"  14       16       18

[:, :, 5] =
       "one"    "two"    "three"
  "a"  19       21       23
  "b"  20       22       24

julia> B = A["a", :, :]
3×4 NamedDimsArray(AxisArray(::Array{Int64,2}
  • axes:
     y = ["one", "two", "three"]
     z = 2:5
))
           2  3   4   5
  "one"    1   7  13  19
  "two"    3   9  15  21
  "three"  5  11  17  23

julia> C = B["one",:]
4-element NamedDimsArray(AxisArray(::Array{Int64,1}
  • axes:
     z = 2:5
))
     1
  2   1
  3   7
  4  13
  5  19

offset([collection,] x)

Examples

julia> using AxisIndices

julia> AxisArray(ones(3), offset(2))
3-element AxisArray(::Array{Float64,1}
  • axes:
     1 = 3:5
)
     1
  3  1.0
  4  1.0
  5  1.0

OffsetArray

An array whose axes are all OffsetAxis

OffsetAxis(keys::AbstractUnitRange{<:Integer}, parent::AbstractUnitRange{<:Integer}[, check_length::Bool=true])
OffsetAxis(offset::Integer, parent::AbstractUnitRange{<:Integer})

An axis that has the indexing behavior of an AbstractOffsetAxis and retains an offset from its underlying indices in its keys. Note that offset is only the offset from the parent indices. If OffsetAxis is part of an AxisArray, the number returned by ArrayInterface.offsets refers to the offset from zero, not the offset found in this axis.

Examples

Users may construct an OffsetAxis by providing an from a set of indices.

julia> using AxisIndices

julia> axis = AxisIndices.OffsetAxis(-2, 1:3)
offset(-2)(SimpleAxis(1:3))

In this instance the first index of the wrapped indices is 1 (firstindex(indices(axis))) but adding the offset (-2) moves it to -1.

julia> firstindex(axis)
-1

julia> axis[-1]
-1

Similarly, the last index is move by -2.

julia> lastindex(axis)
1

julia> axis[1]
1

This means that traditional one based indexing no longer applies and may result in errors.

julia> axis[3]
ERROR: BoundsError: attempt to access offset(-2)(SimpleAxis(1:3)) at index [3]
[...]

When an OffsetAxis is reconstructed the offset from indices are presserved.

julia> axis[0:1]  # offset of -2 still applies
offset(-2)(SimpleAxis(2:3))

OffsetVector

A vector whose axis is OffsetAxis

one_pad(x; first_pad=0, last_pad=0, sym_pad=nothing)

The border elements return oneunit(eltype(A)), where A is the parent array being padded.

PaddedInitializer

Abstract type for padding styles.

SimpleAxis(v)

Povides an AbstractAxis interface for any AbstractUnitRange, v. v will be considered both the values and keys of the return instance.

Examples

A SimpleAxis is useful for giving a standard set of indices the ability to use the filtering syntax for indexing.

julia> using AxisIndices, StaticRanges

julia> x = SimpleAxis(2:10)
SimpleAxis(2:10)

julia> x[2]
2

julia> x[==(2)]
2

julia> x[2] == x[==(2)]  # keys and values are same
true

julia> x[>(2)]
SimpleAxis(3:10)

julia> x[>(2)]
SimpleAxis(3:10)

julia> x[1]
ERROR: BoundsError: attempt to access SimpleAxis(2:10) at index [1]
[...]

StructAxis{T}

An axis that uses a structure T to form its keys.

symmetric_pad(x; first_pad=0, last_pad=0, sym_pad=nothing)

The border elements reflect relative to a position between elements. That is, the border pixel is omitted when mirroring.

\[\boxed{ \begin{array}{l|c|r} e\, d\, c\, b & a \, b \, c \, d \, e \, f & e \, d \, c \, b \end{array} }\]

zero_pad(x; first_pad=0, last_pad=0, sym_pad=nothing)

The border elements return zero(eltype(A)), where A is the parent array being padded.