OffsetArrays.jl

Documentation	Build Status	Code coverage	Version

OffsetArrays provides Julia users with arrays that have arbitrary indices, similar to those found in some other programming languages like Fortran.

An OffsetArray is a lightweight wrapper around an AbstractArray that shifts its indices. Generally, indexing into an OffsetArray should be as performant as the parent array.

There are two ways to construct OffsetArrays: by specifying the axes of the array, or by specifying its origin.

The first way to construct an OffsetArray by specifying its axes is:

OA = OffsetArray(A, axis1, axis2, ...)

where you want OA to have axes (axis1, axis2, ...) and be indexed by values that fall within these axis ranges. Example:

julia> using OffsetArrays

julia> A = Float64.(reshape(1:15, 3, 5))
3×5 Matrix{Float64}:
 1.0  4.0  7.0  10.0  13.0
 2.0  5.0  8.0  11.0  14.0
 3.0  6.0  9.0  12.0  15.0

julia> axes(A) # indices of a Matrix start from 1 along each axis
(Base.OneTo(3), Base.OneTo(5))

julia> OA = OffsetArray(A, -1:1, 0:4) # OA will have the axes (-1:1, 0:4)
3×5 OffsetArray(::Matrix{Float64}, -1:1, 0:4) with eltype Float64 with indices -1:1×0:4:
 1.0  4.0  7.0  10.0  13.0
 2.0  5.0  8.0  11.0  14.0
 3.0  6.0  9.0  12.0  15.0

julia> OA[-1, 0]
1.0

julia> OA[1, 4]
15.0

The second way to construct an OffsetArray is by specifying the origin, that is, the first index along each axis. This is particularly useful if one wants, eg., arrays that are 0-indexed as opposed to 1-indexed.

A convenient way to construct an OffsetArray this way is by using OffsetArrays.Origin:

julia> using OffsetArrays: Origin

julia> Origin(0)(A) # indices begin at 0 along all axes
3×5 OffsetArray(::Matrix{Float64}, 0:2, 0:4) with eltype Float64 with indices 0:2×0:4:
 1.0  4.0  7.0  10.0  13.0
 2.0  5.0  8.0  11.0  14.0
 3.0  6.0  9.0  12.0  15.0

julia> Origin(2, 3)(A) # indices begin at 2 along the first axis and 3 along the second
3×5 OffsetArray(::Matrix{Float64}, 2:4, 3:7) with eltype Float64 with indices 2:4×3:7:
 1.0  4.0  7.0  10.0  13.0
 2.0  5.0  8.0  11.0  14.0
 3.0  6.0  9.0  12.0  15.0

While the examples here refer to the common case where the parent arrays have indices starting at 1, this is not necessary. An OffsetArray may wrap any array that has integer indices, irrespective of where the indices begin.

Certain libraries, such as LinearAlgebra, require arrays to be indexed from 1. Passing an OffsetArray with shifted indices would lead to an error here.

julia> A = Float64.(reshape(1:16, 4, 4));

julia> AO = Origin(0)(A);

julia> using LinearAlgebra

julia> Diagonal(AO)
ERROR: ArgumentError: offset arrays are not supported but got an array with index other than 1

The way to obtain a 1-indexed array from an OffsetArray is by using OffsetArrays.no_offset_view.

An example of this is:

julia> OffsetArrays.no_offset_view(AO)
4×4 Matrix{Float64}:
 1.0  5.0   9.0  13.0
 2.0  6.0  10.0  14.0
 3.0  7.0  11.0  15.0
 4.0  8.0  12.0  16.0

This may now be passed to LinearAlgebra:

julia> D = Diagonal(OffsetArrays.no_offset_view(AO))
4×4 Diagonal{Float64, Vector{Float64}}:
 1.0   ⋅     ⋅     ⋅
  ⋅   6.0    ⋅     ⋅
  ⋅    ⋅   11.0    ⋅
  ⋅    ⋅     ⋅   16.0

If we want to restore the original indices of AO, we may wrap an OffsetArray around the Diagonal as:

julia> Origin(AO)(D)
4×4 OffsetArray(::Diagonal{Float64, Vector{Float64}}, 0:3, 0:3) with eltype Float64 with indices 0:3×0:3:
 1.0   ⋅     ⋅     ⋅
  ⋅   6.0    ⋅     ⋅
  ⋅    ⋅   11.0    ⋅
  ⋅    ⋅     ⋅   16.0

Here, Origin(AO) is able to automatically infer and use the indices of AO.

For some applications, OffsetArrays give users an easy-to-understand interface. However, handling the non-conventional axes of OffsetArrays requires extra care. Otherwise, the code might error, crash, or return incorrect results. You can read the Julialang documentation on offset for more information. Here we briefly summarize some of the best practices for users and package authors.

You don't need to support offset arrays for internal functions that only consume standard 1-based arrays -- it doesn't change or improve anything.

You don't need to support offset arrays for functions that have no well-defined behavior on custom axes. For instance, many linear algebra functions such as matrix multiplication A * B does not have an agreed behavior for offset arrays. In this case, it is a better practice to let users do the conversion.

The helper function Base.require_one_based_indexing can be used to early check the axes and throw a meaningful error. If your interface functions do not intend to support offset arrays, we recommend you add this check before starting the real computation.

Many implementations assume the array axes start at 1 by writing loops such as for i in 1:length(x) or for i in 1:size(x, 1). A better practice is to use for i in eachindex(x) or for i in axes(x, 1) -- axes provides more information than size with no performance overhead.

Also, if you know what indices type you want to use, LinearIndices and CartesianIndices allow you to loop multidimensional arrays efficiently without worrying about the axes.

For package authors that declare support for AbstractArray, we recommend having a few test cases against OffsetArray to ensure the function works well for arrays with custom axes. This gives you more confidence that users don't run into strange situations.

For package users that want to use offset arrays, many numerical correctness issues come from the fact that @inbounds is used inappropriately with the 1-based indexing assumption. Thus for debug purposes, it is not a bad idea to start Julia with --check-bounds=yes, which turns all @inbounds into a no-op and uncover potential out-of-bound errors.