# API

## Arrays

DimensionalData.AbstractDimArrayType
AbstractDimArray <: AbstractArray

Abstract supertype for all "dim" arrays.

These arrays return a Tuple of Dimension from a dims method, and can be rebuilt using rebuild.

parent must return the source array.

They should have metadata, name and refdims methods, although these are optional.

A rebuild method for AbstractDimArray must accept data, dims, refdims, name, metadata arguments.

Indexing AbstractDimArray with non-range AbstractArray has undefined effects on the Dimension index. Use forward-ordered arrays only"

source
DimensionalData.DimArrayType
DimArray <: AbstractDimArray

DimArray(data, dims::Tuple; refdims=(), name=NoName(), metadata=NoMetadata())

The main concrete subtype of AbstractDimArray.

DimArray maintains and updates its Dimensions through transformations and moves dimensions to reference dimension refdims after reducing operations (like e.g. mean).

Arguments

• data: An AbstractArray.
• dims: A Tuple of Dimension
• name: A string name for the array. Shows in plots and tables.
• refdims: refence dimensions. Usually set programmatically to track past slices and reductions of dimension for labelling and reconstruction.
• metadata: Dict or Metadata object, or NoMetadata()

Indexing can be done with all regular indices, or with Dimensions and/or Selectors.

Indexing AbstractDimArray with non-range AbstractArray has undefined effects on the Dimension index. Use forward-ordered arrays only"

Example:

using Dates, DimensionalData

ti = (Ti(DateTime(2001):Month(1):DateTime(2001,12)),
x = X(10:10:100))
A = DimArray(rand(12,10), (ti, x), "example")

julia> A[X(Near([12, 35])), Ti(At(DateTime(2001,5)))];

julia> A[Near(DateTime(2001, 5, 4)), Between(20, 50)];
source

## Multi-array datasets

DimensionalData.AbstractDimStackType
AbstractDimStack

Abstract supertype for dimensional stacks.

These have multiple layers of data, but share dimensions.

Notably, their behaviour lies somewhere between a DimArray and a NamedTuple:

• indexing with a Symbol as in dimstack[:symbol] returns a DimArray layer.
• iteration amd map are apply over array layers, as indexed with a Symbol.
• getindex and many base methods are applied as for DimArray - to avoid the need to allways use map.

This design gives very succinct code when working with many-layered, mixed-dimension objects. But it may be jarring initially - the most surprising outcome is that dimstack[1] will return a NamedTuple of values for the first index in all layers, while first(dimstack) will return the first value of the iterator - the DimArray for the first layer.

See DimStack for the concrete implementation. Most methods are defined on the abstract type.

To extend AbstractDimStack, implement rebuild and rebuild_from_arrays.

source
DimensionalData.DimStackType
DimStack <: AbstractDimStack

DimStack(data::AbstractDimArray...)
DimStack(data::Tuple{Vararg{<:AbstractDimArray}})
DimStack(data::NamedTuple{Keys,Vararg{<:AbstractDimArray}})
DimStack(data::NamedTuple, dims::DimTuple; metadata=NoMetadata())

DimStack holds multiple objects sharing some dimensions, in a NamedTuple.

Notably, their behaviour lies somewhere between a DimArray and a NamedTuple:

• indexing with a Symbol as in dimstack[:symbol] returns a DimArray layer.
• iteration amd map are apply over array layers, as indexed with a Symbol.
• getindex or view with Int, Dimensions or Selectors that resolve to Int will return a NamedTuple of values from each layer in the stack. This has very good performace, and avoids the need to always use map.
• getindex or view with a Vector or Colon will return another DimStack where all data layers have been sliced.
• setindex! must pass a Tuple or NamedTuple maching the layers.
• many base and Statistics methods (sum, mean etc) will work as for a DimArray again removing the need to use map.

For example, here we take the mean over the time dimension for all layers :

mean(mydimstack; dims=Ti)

And this equivalent to:

map(A -> mean(A; dims=Ti), mydimstack)

This design gives succinct code when working with many-layered, mixed-dimension objects.

But it may be jarring initially - the most surprising outcome is that dimstack[1] will return a NamedTuple of values for the first index in all layers, while first(dimstack) will return the first value of the iterator - the DimArray for the first layer.

DimStack can be constructed from multiple AbstractDimArray or a NamedTuple of AbstractArray and a matching dims tuple.

Most Base and Statistics methods that apply to AbstractArray can be used on all layers of the stack simulataneously. The result is a DimStack, or a NamedTuple if methods like mean are used without dims arguments, and return a single non-array value.

Example

julia> using DimensionalData

julia> A = [1.0 2.0 3.0; 4.0 5.0 6.0];

julia> dimz = (X([:a, :b]), Y(10.0:10.0:30.0))
X Symbol[a, b],
Y 10.0:10.0:30.0

julia> da1 = DimArray(1A, dimz; name=:one);

julia> da2 = DimArray(2A, dimz; name=:two);

julia> da3 = DimArray(3A, dimz; name=:three);

julia> s = DimStack(da1, da2, da3);

julia> s[At(:b), At(10.0)]
(one = 4.0, two = 8.0, three = 12.0)

julia> s[X(At(:a))] isa DimStack
true
source

## Dimension indices generators

DimensionalData.DimIndicesType
DimIndices <: AbstractArray

DimIndices(x)
DimIndices(dims::Tuple)
DimIndices(dims::Dimension)

Like CartesianIndices, but for Dimensions. Behaves as an Array of Tuple of Dimension(i) for all combinations of the axis indices of dims.

This can be used to view/index into arbitrary dimensions over an array, and is especially useful when combined with otherdims, to iterate over the indices of unknown dimension.

source
DimensionalData.DimKeysType
DimKeys <: AbstractArray

DimKeys(x)
DimKeys(dims::Tuple)
DimKeys(dims::Dimension)

Like CartesianIndices, but for the lookup values of Dimensions. Behaves as an Array of Tuple of Dimension(At(lookupvalue)) for all combinations of the lookup values of dims.

source
DimensionalData.DimPointsType
DimPoints <: AbstractArray

DimPoints(x; order)
DimPoints(dims::Tuple; order)
DimPoints(dims::Dimension; order)

Like CartesianIndices, but for the point values of the dimension index. Behaves as an Array of Tuple lookup values (whatever they are) for all combinations of the lookup values of dims.

Either a Dimension, a Tuple of Dimension or an object that defines a dims method can be passed in.

Keywords

• order: determines the order of the points, the same as the order of dims by default.
source

## Tables.jl/TableTraits.jl interface

DimensionalData.DimTableType
DimTable <: AbstractDimTable

DimTable(A::AbstractDimArray)

Construct a Tables.jl/TableTraits.jl compatible object out of an AbstractDimArray.

This table will have a column for the array data and columns for each Dimension index, as a [DimColumn]. These are lazy, and generated as required.

Column names are converted from the dimension types using DimensionalData.dim2key. This means type Ti becomes the column name :Ti, and Dim{:custom} becomes :custom.

To get dimension columns, you can index with Dimension (X()) or Dimension type (X) as well as the regular Int or Symbol.

source
DimensionalData.DimColumnType
DimColumn{T,D<:Dimension} <: AbstractVector{T}

DimColumn(dim::Dimension, dims::Tuple{Vararg{<:DimTuple}})
DimColumn(dim::DimColumn, length::Int, dimstride::Int)

A table column based on a Dimension and it's relationship with other Dimensions in dims.

length is the product of all dim lengths (usually the length of the corresponding array data), while stride is the product of the preceding dimension lengths, which may or may not be the real stride of the corresponding array depending on the data type. For A isa Array, the dimstride will match the stride.

When the second argument is a Tuple of Dimension, the length and dimstride fields are calculated from the dimensions, relative to the column dimension dim.

This object will be returned as a column of DimTable.

source

## Common methods

Common functions for obtaining information from objects:

DimensionalData.Dimensions.dimsFunction
dims(x, [dims::Tuple]) => Tuple{Vararg{<:Dimension}}
dims(x, dim) => Dimension

Return a tuple of Dimensions for an object, in the order that matches the axes or columns of the underlying data.

dims can be Dimension, Dimension types, or Symbols for Dim{Symbol}.

The default is to return nothing.

source
DimensionalData.Dimensions.refdimsFunction
refdims(x, [dims::Tuple]) => Tuple{Vararg{<:Dimension}}
refdims(x, dim) => Dimension

Reference dimensions for an array that is a slice or view of another array with more dimensions.

slicedims(a, dims) returns a tuple containing the current new dimensions and the new reference dimensions. Refdims can be stored in a field or disgarded, as it is mostly to give context to plots. Ignoring refdims will simply leave some captions empty.

The default is to return an empty Tuple ().

source
DimensionalData.Dimensions.LookupArrays.metadataFunction
metadata(x) => (object metadata)
metadata(xs::Tuple) => Tuple

Returns the metadata for an object or for the specified dimension(s)

Second argument dims can be Dimensions, Dimension types, or Symbols for Dim{Symbol}.

source
DimensionalData.Dimensions.nameFunction
name(x) => String
name(xs:Tuple) => NTuple{N,String}
name(x, dims::Tuple) => NTuple{N,String}
name(x, dim) => String

Get the name of an array or Dimension, or a tuple of of either.

Second argument dims can be Dimensions, Dimension types, or Symbols for Dim{Symbol}.

source

Utility methods for transforming DimensionalData objects:

DimensionalData.Dimensions.LookupArrays.setFunction
set(x, val)
set(x, args::Pairs...) => x with updated field/s
set(x, args...; kw...) => x with updated field/s
set(x, args::Tuple{Vararg{<:Dimension}}; kw...) => x with updated field/s

set(dim::Dimension, index::AbstractArray) => Dimension
set(dim::Dimension, lookup::LookupArray) => Dimension
set(dim::Dimension, lookupcomponent::LookupArrayTrait) => Dimension
set(dim::Dimension, metadata::AbstractMetadata) => Dimension

Set the properties of an object, its internal data or the traits of its dimensions and lookup index.

As DimensionalData is so strongly typed you do not need to specify what field of a LookupArray to set - there is no ambiguity.

To set fields of a LookupArray you need to specify the dimension. This can be done using X => val pairs, X = val keyword arguments, or X(val) wrapped arguments.

When a Dimension or LookupArray is passed to set to replace the existing ones, fields that are not set will keep their original values.

Notes:

Changing a lookup index range/vector will also update the step size and order where applicable.

Setting the Order like ForwardOrdered will not reverse the array or dimension to match. Use reverse and reorder to do this.

Examples

julia> using DimensionalData; const DD = DimensionalData
DimensionalData

julia> da = DimArray(zeros(3, 4), (custom=10.0:010.0:30.0, Z=-20:010.0:10.0));

julia> set(da, ones(3, 4))
3×4 DimArray{Float64,2} with dimensions:
Dim{:custom} Sampled{Float64} 10.0:10.0:30.0 ForwardOrdered Regular Points,
Z Sampled{Float64} -20.0:10.0:10.0 ForwardOrdered Regular Points
-20.0  -10.0  0.0  10.0
10.0    1.0    1.0  1.0   1.0
20.0    1.0    1.0  1.0   1.0
30.0    1.0    1.0  1.0   1.0 

Change the Dimension wrapper type:

julia> set(da, :Z => Ti, :custom => Z)
3×4 DimArray{Float64,2} with dimensions:
Z Sampled{Float64} 10.0:10.0:30.0 ForwardOrdered Regular Points,
Ti Sampled{Float64} -20.0:10.0:10.0 ForwardOrdered Regular Points
-20.0  -10.0  0.0  10.0
10.0    0.0    0.0  0.0   0.0
20.0    0.0    0.0  0.0   0.0
30.0    0.0    0.0  0.0   0.0 

Change the lookup Vector:

julia> set(da, Z => [:a, :b, :c, :d], :custom => [4, 5, 6])
3×4 DimArray{Float64,2} with dimensions:
Dim{:custom} Sampled{Int64} Int64[4, 5, 6] ForwardOrdered Regular Points,
Z Sampled{Symbol} Symbol[a, b, c, d] ForwardOrdered Regular Points
:a   :b   :c   :d
4  0.0  0.0  0.0  0.0
5  0.0  0.0  0.0  0.0
6  0.0  0.0  0.0  0.0

Change the LookupArray type:

julia> set(da, Z=DD.NoLookup(), custom=DD.Sampled())
3×4 DimArray{Float64,2} with dimensions:
Dim{:custom} Sampled{Float64} 10.0:10.0:30.0 ForwardOrdered Regular Points,
Z
10.0  0.0  0.0  0.0  0.0
20.0  0.0  0.0  0.0  0.0
30.0  0.0  0.0  0.0  0.0

Change the Sampling trait:

julia> set(da, :custom => DD.Irregular(10, 12), Z => DD.Regular(9.9))
3×4 DimArray{Float64,2} with dimensions:
Dim{:custom} Sampled{Float64} 10.0:10.0:30.0 ForwardOrdered Irregular Points,
Z Sampled{Float64} -20.0:10.0:10.0 ForwardOrdered Regular Points
-20.0  -10.0  0.0  10.0
10.0    0.0    0.0  0.0   0.0
20.0    0.0    0.0  0.0   0.0
30.0    0.0    0.0  0.0   0.0
source
DimensionalData.Dimensions.LookupArrays.rebuildFunction
rebuild(x, args...)
rebuild(x; kw...)

Rebuild an object struct with updated field values.

x can be a AbstractDimArray, a Dimension, LookupArray or other custom types.

This is an abstraction that alows inbuilt and custom types to be rebuilt to update their fields, as most objects in DimensionalData.jl are immutable.

The arguments version can be concise but depends on a fixed order defined for some DimensionalData objects. It should be defined based on the object type in DimensionalData, adding the fields specific to your object.

The keyword version ignores order, and is mostly automated using ConstructionBase.setproperties. It should only be defined if your object has missing fields or fields with different names to DimensionalData objects.

The arguments required are defined for the abstract type that has a rebuild method.

source
DimensionalData.modifyFunction
modify(f, A::AbstractDimArray) => AbstractDimArray
modify(f, s::AbstractDimStack) => AbstractDimStack
modify(f, dim::Dimension) => Dimension
modify(f, x, lookupdim::Dimension) => typeof(x)

Modify the parent data, rebuilding the object wrapper without change. f must return a AbstractArray of the same size as the original.

This method is mostly useful as a way of swapping the parent array type of an object.

Example

If we have a previously-defined DimArray, we can copy it to an Nvidia GPU with:

A = DimArray(rand(100, 100), (X, Y))
modify(CuArray, A)

This also works for all the data layers in a DimStack.

source
DimensionalData.broadcast_dimsFunction
brodadcast_dims(f, sources::AbstractDimArray...) => AbstractDimArray

Broadcast function f over the AbstractDimArrays in sources, permuting and reshaping dimensions to match where required. The result will contain all the dimensions in all passed in arrays in the order in which they are found.

Arguments

• sources: AbstractDimArrays to broadcast over with f.

This is like broadcasting over every slice of A if it is sliced by the dimensions of B.

source
DimensionalData.broadcast_dims!Function
brodadcast_dims!(f, dest::AbstractDimArray, sources::AbstractDimArray...) => dest

Broadcast function f over the AbstractDimArrays in sources, writing to dest. sources are permuting and reshaping dimensions to match where required.

The result will contain all the dimensions in all passed in arrays, in the order in which they are found.

Arguments

• dest: AbstractDimArray to update.
• sources: AbstractDimArrays to broadcast over with f.
source
DimensionalData.reorderFunction
reorder(A::AbstractDimArray, order::Pair) => AbstractDimArray
reorder(A::Dimension, order::Order) => AbstractDimArray

Reorder every dims index/array to order, or reorder index for the the given dimension(s) to the Order they wrap.

order can be an Order, or Dimeension => Order pairs.

If no axis reversal is required the same objects will be returned, without allocation.

source
Base.catFunction
Base.cat(stacks::AbstractDimStack...; [keys=keys(stacks[1])], dims)

Concatenate all or a subset of layers for all passed in stacks.

Keywords

• keys: Tuple of Symbol for the stack keys to concatenate.
• dims: Dimension of child array to concatenate on.

Example

Concatenate the :seasurfacetemp and :humidity layers in the time dimension:

cat(stacks...; keys=(:sea_surface_temp, :humidity), dims=Ti)
source
Base.mapFunction
Base.map(f, stacks::AbstractDimStack...)

Apply function f to each layer of the stacks.

If f returns DimArrays the result will be another DimStack. Other values will be returned in a NamedTuple.

source
Base.copy!Function
Base.copy!(dst::AbstractArray, src::AbstractGimStack, key::Key)

Copy the stack layer key to dst, which can be any AbstractArray.

Example

Copy the :humidity layer from stack to array.

copy!(array, stack, :humidity)
source
Base.copy!(dst::AbstractDimStack, src::AbstractDimStack, [keys=keys(dst)])

Copy all or a subset of layers from one stack to another.

Example

Copy just the :sea_surface_temp and :humidity layers from src to dst.

copy!(dst::AbstractDimStack, src::AbstractDimStack, keys=(:sea_surface_temp, :humidity))
source

Most base methods work as expected, using Dimension wherever a dims keyword is used. They are not allspecifically documented here.

Shorthand constructors:

Base.fillFunction
Base.fill(x, dims::Dimension...; kw...) => DimArray
Base.fill(x, dims::Tuple{Vararg{<:Dimension}}; kw...) => DimArray

Create a DimArray with a fill value of x.

There are two kinds of Dimension value acepted:

• A Dimension holding an AbstractVector will set the dimension index to that AbstractVector, and detect the dimension lookup.
• A Dimension holding an Integer will set the length of the axis, and set the dimension lookup to NoLookup.

Keywords are the same as for DimArray.

Example

julia> using DimensionalData

julia> rand(Bool, X(2), Y(4))
2×4 DimArray{Bool,2} with dimensions: X, Y
1  0  0  1
1  0  1  1
source
Base.randFunction
Base.rand(x, dims::Dimension...; kw...) => DimArray
Base.rand(x, dims::Tuple{Vararg{<:Dimension}}; kw...) => DimArray
Base.rand(r::AbstractRNG, x, dims::Tuple{Vararg{<:Dimension}}; kw...) => DimArray
Base.rand(r::AbstractRNG, x, dims::Dimension...; kw...) => DimArray

Create a DimArray of random values.

There are two kinds of Dimension value acepted:

• A Dimension holding an AbstractVector will set the dimension index to that AbstractVector, and detect the dimension lookup.
• A Dimension holding an Integer will set the length of the axis, and set the dimension lookup to NoLookup.

Keywords are the same as for DimArray.

Example

julia> using DimensionalData

julia> rand(Bool, X(2), Y(4))
2×4 DimArray{Bool,2} with dimensions: X, Y
1  0  0  1
1  0  1  1

julia> rand(X([:a, :b, :c]), Y(100.0:50:200.0))
3×3 DimArray{Float64,2} with dimensions:
X: Symbol[a, b, c] Categorical: Unordered,
Y: 100.0:50.0:200.0 Sampled: Ordered Regular Points
0.43204   0.835111  0.624231
0.752868  0.471638  0.193652
0.484558  0.846559  0.455256
source
Base.zerosFunction
Base.zeros(x, dims::Dimension...; kw...) => DimArray
Base.zeros(x, dims::Tuple{Vararg{Dimension}}; kw...) => DimArray

Create a DimArray of zeros.

There are two kinds of Dimension value acepted:

• A Dimension holding an AbstractVector will set the dimension index to that AbstractVector, and detect the dimension lookup.
• A Dimension holding an Integer will set the length of the axis, and set the dimension lookup to NoLookup.

Keywords are the same as for DimArray.

Example

julia> using DimensionalData

julia> zeros(Bool, X(2), Y(4))
2×4 DimArray{Bool,2} with dimensions: X, Y
0  0  0  0
0  0  0  0

julia> zeros(X([:a, :b, :c]), Y(100.0:50:200.0))
3×3 DimArray{Float64,2} with dimensions:
X: Symbol[a, b, c] Categorical: Unordered,
Y: 100.0:50.0:200.0 Sampled: Ordered Regular Points
0.0  0.0  0.0
0.0  0.0  0.0
0.0  0.0  0.0
source
Base.onesFunction
Base.ones(x, dims::Dimension...; kw...) => DimArray
Base.ones(x, dims::Tuple{Vararg{Dimension}}; kw...) => DimArray

Create a DimArray of ones.

There are two kinds of Dimension value acepted:

• A Dimension holding an AbstractVector will set the dimension index to that AbstractVector, and detect the dimension lookup.
• A Dimension holding an Integer will set the length of the axis, and set the dimension lookup to NoLookup.

Keywords are the same as for DimArray.

Example

julia> using DimensionalData

julia> ones(Bool, X(2), Y(4))
2×4 DimArray{Bool,2} with dimensions: X, Y
1  1  1  1
1  1  1  1

julia> ones(X([:a, :b, :c]), Y(100.0:50:200.0))
3×3 DimArray{Float64,2} with dimensions:
X: Symbol[a, b, c] Categorical: Unordered,
Y: 100.0:50.0:200.0 Sampled: Ordered Regular Points
1.0  1.0  1.0
1.0  1.0  1.0
1.0  1.0  1.0
source

# Dimensions

Handling of Dimensions is kept in a sub-module Dimensions.

Dimensions have a type-heirarchy that organises plotting and dimension matching.

DimensionalData.Dimensions.DimensionType
Dimension

Abstract supertype of all dimension types.

Example concrete implementations are X, Y, Z, Ti (Time), and the custom [Dim]@ref) dimension.

Dimensions label the axes of an AbstractDimArray, or other dimensional objects, and are used to index into the array.

They may also provide an alternate index to lookup for each array axis. This may be any AbstractVector matching the array axis length, or a Val holding a tuple for compile-time index lookups.

Dimensions also have lookup and metadata fields.

lookup gives more details about the dimension, such as that it is Categorical or Sampled as Points or Intervals along some transect. DimensionalData will attempt to guess the lookup from the passed-in index value.

Example:

using DimensionalData, Dates

x = X(2:2:10)
y = Y(['a', 'b', 'c'])
ti = Ti(DateTime(2021, 1):Month(1):DateTime(2021, 12))

A = DimArray(zeros(3, 5, 12), (y, x, ti))

# output

3×5×12 DimArray{Float64,3} with dimensions:
Y Categorical{Char} Char[a, b, c] ForwardOrdered,
X Sampled{Int64} 2:2:10 ForwardOrdered Regular Points,
Ti Sampled{DateTime} DateTime("2021-01-01T00:00:00"):Month(1):DateTime("2021-12-01T00:00:00") ForwardOrdered Regular Points
[:, :, 1]
2    4    6    8    10
'a'  0.0  0.0  0.0  0.0   0.0
'b'  0.0  0.0  0.0  0.0   0.0
'c'  0.0  0.0  0.0  0.0   0.0
[and 11 more slices...]

For simplicity, the same Dimension types are also used as wrappers in getindex, like:

x = A[X(2), Y(3)]

# output

12-element DimArray{Float64,1} with dimensions:
Ti Sampled{DateTime} DateTime("2021-01-01T00:00:00"):Month(1):DateTime("2021-12-01T00:00:00") ForwardOrdered Regular Points
and reference dimensions:
Y Categorical{Char} Char[c] ForwardOrdered,
X Sampled{Int64} 4:2:4 ForwardOrdered Regular Points
2021-01-01T00:00:00  0.0
2021-02-01T00:00:00  0.0
2021-03-01T00:00:00  0.0
2021-04-01T00:00:00  0.0
2021-05-01T00:00:00  0.0
2021-06-01T00:00:00  0.0
2021-07-01T00:00:00  0.0
2021-08-01T00:00:00  0.0
2021-09-01T00:00:00  0.0
2021-10-01T00:00:00  0.0
2021-11-01T00:00:00  0.0
2021-12-01T00:00:00  0.0

A Dimension can also wrap Selector.

x = A[X(Between(3, 4)), Y(At('b'))]

# output

1×12 DimArray{Float64,2} with dimensions:
X Sampled{Int64} 4:2:4 ForwardOrdered Regular Points,
Ti Sampled{DateTime} DateTime("2021-01-01T00:00:00"):Month(1):DateTime("2021-12-01T00:00:00") ForwardOrdered Regular Points
and reference dimensions:
Y Categorical{Char} Char[b] ForwardOrdered
2021-01-01T00:00:00  …   2021-12-01T00:00:00
4  0.0                                  0.0

Dimension objects may have lookup and metadata fields to track additional information about the data and the index, and their relationship.

source
DimensionalData.Dimensions.TimeDimType
TimeDim <: IndependentDim

Abstract supertype for all time dimensions.

In a TimeDime with Interval sampling the locus will automatically be set to Start(). Dates and times generally refer to the start of a month, hour, second etc., not the central point as is more common with spatial data. 

source
DimensionalData.Dimensions.TiType

m Ti <: TimeDim

Ti(val=:)

Time Dimension. Ti <: TimeDim <: IndependentDim

Time is already used by Dates, and T is a common type parameter, We use Ti to avoid clashes.

Example:

timedim = Ti(DateTime(2021, 1):Month(1):DateTime(2021, 12))
# Or
val = A[Ti(1)]
# Or
mean(A; dims=Ti)
source
DimensionalData.Dimensions.DimType
Dim{S}(val=:)

A generic dimension. For use when custom dims are required when loading data from a file. Can be used as keyword arguments for indexing.

Dimension types take precedence over same named Dim types when indexing with symbols, or e.g. creating Tables.jl keys.

using DimensionalData

dim = Dim{:custom}(['a', 'b', 'c'])

# output

Dim{:custom} Char[a, b, c]
source
DimensionalData.Dimensions.CoordType
Coord <: Dimension

A coordinate dimension itself holds dimensions.

This allows combining point data with other dimensions, such as time.

Example

julia> using DimensionalData

julia> dim = Coord([(1.0,1.0,1.0), (1.0,2.0,2.0), (3.0,4.0,4.0), (1.0,3.0,4.0)], (X(), Y(), Z()))
Coord ::
val: Tuple{Float64, Float64, Float64}[(1.0, 1.0, 1.0), (1.0, 2.0, 2.0), (3.0, 4.0, 4.0), (1.0, 3.0,
4.0)]
lookup: CoordLookupArray
Coord{Vector{Tuple{Float64, Float64, Float64}}, DimensionalData.CoordLookupArray{Tuple{X{Colon, AutoLookup{Auto

julia> da = DimArray(0.1:0.1:0.4, dim)
4-element DimArray{Float64,1} with dimensions:
Coord (): Tuple{Float64, Float64, Float64}[(1.0, 1.0, 1.0), (1.0, 2.0, 2.0), (3.0, 4.0, 4.0), (1.0,
3.0, 4.0)]
CoordLookupArray
0.1
0.2
0.3
0.4

julia> da[Coord(Z(At(1.0)), Y(Between(1, 3)))]
1-element DimArray{Float64,1} with dimensions:
Coord (): Tuple{Float64, Float64, Float64}[(1.0, 1.0, 1.0)] CoordLookupArray
0.1

julia> da[Coord(4)] == 0.4
true

julia> da[Coord(Between(1, 5), :, At(4.0))]
2-element DimArray{Float64,1} with dimensions:
Coord (): Tuple{Float64, Float64, Float64}[(3.0, 4.0, 4.0), (1.0, 3.0, 4.0)] CoordLookupArray
0.3
0.4
source
DimensionalData.Dimensions.@dimMacro
@dim typ [supertype=Dimension] [name::String=string(typ)]

Macro to easily define new dimensions. The supertype will be inserted into the type of the dim. The default is simply YourDim <: Dimension. Making a Dimesion inherit from XDim, YDim, ZDim or TimeDim will affect automatic plot layout and other methods that dispatch on these types. <: YDim are plotted on the Y axis, <: XDim on the X axis, etc.

Example:

using DimensionalData
using DimensionalData: @dim, YDim, XDim
@dim Lat YDim "latitude"
@dim Lon XDim "Longitude"
# output

source

### Exported methopds

DimensionalData.Dimensions.hasdimFunction
hasdim([f], x, lookup::Tuple) => NTUple{Bool}
hasdim([f], x, lookups...) => NTUple{Bool}
hasdim([f], x, lookup) => Bool

Check if an object x has dimensions that match or inherit from the lookup dimensions.

Arguments

• x: any object with a dims method, a Tuple of Dimension or a single Dimension.
• lookup: Tuple or single Dimension or dimension Type.
• f: <: by default, but can be >: to match abstract types to concrete types.

Check if an object or tuple contains an Dimension, or a tuple of dimensions.

Example

julia> using DimensionalData

julia> A = DimArray(ones(10, 10, 10), (X, Y, Z));

julia> hasdim(A, X)
true

julia> hasdim(A, (Z, X, Y))
(true, true, true)

julia> hasdim(A, Ti)
false
source
DimensionalData.Dimensions.dimnumFunction
dimnum(x, lookup::Tuple) => NTuple{Int}
dimnum(x, lookup) => Int

Get the number(s) of Dimension(s) as ordered in the dimensions of an object.

Arguments

• x: any object with a dims method, a Tuple of Dimension or a single Dimension.
• lookup: Tuple, Array or single Dimension or dimension Type.

The return type will be a Tuple of Int or a single Int, depending on wether lookup is a Tuple or single Dimension.

Example

julia> using DimensionalData

julia> A = DimArray(ones(10, 10, 10), (X, Y, Z));

julia> dimnum(A, (Z, X, Y))
(3, 1, 2)

julia> dimnum(A, Y)
2
source

### Non-exported methods

DimensionalData.Dimensions.lookupFunction
lookup(x::Dimension) => LookupArray
lookup(x, [dims::Tuple]) => Tuple{Vararg{<:LookupArray}}
lookup(x::Tuple) => Tuple{Vararg{<:LookupArray}}
lookup(x, dim) => LookupArray

Returns the LookupArray of a dimension. This dictates properties of the dimension such as array axis and index order, and sampling properties.

dims can be a Dimension, a dimension type, or a tuple of either.

source
DimensionalData.Dimensions.labelFunction
label(x) => String
label(x, dims::Tuple) => NTuple{N,String}
label(x, dim) => String
label(xs::Tuple) => NTuple{N,String}

Get a plot label for data or a dimension. This will include the name and units if they exist, and anything else that should be shown on a plot.

Second argument dims can be Dimensions, Dimension types, or Symbols for Dim{Symbol}.

source
DimensionalData.Dimensions.dim2keyFunction
dim2key(dim::Dimension) => Symbol
dim2key(dims::Type{<:Dimension}) => Symbol
dim2key(dims::Tuple) => Tuple{Symbol,Vararg}

Convert a dimension object to a simbol. X(), Y(), Ti() etc will be converted. to :X, :Y, :Ti, as with any other dims generated with the @dim macro.

All other Dim{S}() dimensions will generate Symbols S.

source
DimensionalData.Dimensions.key2dimFunction
key2dim(s::Symbol) => Dimension
key2dim(dims...) => Tuple{Dimension,Vararg}
key2dim(dims::Tuple) => Tuple{Dimension,Vararg}

Convert a symbol to a dimension object. :X, :Y, :Ti etc will be converted. to X(), Y(), Ti(), as with any other dims generated with the @dim macro.

All other Symbols S will generate Dim{S}() dimensions.

source
DimensionalData.Dimensions.dims2indicesFunction
dims2indices(dim::Dimension, I) => NTuple{Union{Colon,AbstractArray,Int}}

Convert a Dimension or Selector I to indices of Int, AbstractArray or Colon.

source
DimensionalData.Dimensions.formatFunction
format(dims, x) => Tuple{Vararg{<:Dimension,N}}

Format the passed-in dimension(s) dims to match the object x.

Errors are thrown if dims don't match the array dims or size, and any fields holding Auto- objects are filled with guessed objects.

If a LookupArray hasn't been specified, a lookup is chosen based on the type and element type of the index.

source
DimensionalData.Dimensions.reducedimsFunction
reducedims(x, dimstoreduce) => Tuple{Vararg{<:Dimension}}

Replace the specified dimensions with an index of length 1. This is usually to match a new array size where an axis has been reduced with a method like mean or reduce to a length of 1, but the number of dimensions has not changed.

LookupArray traits are also updated to correspond to the change in cell step, sampling type and order.

source
DimensionalData.Dimensions.swapdimsFunction
swapdims(x::T, newdims) => T
swapdims(dims::Tuple, newdims) => Tuple{Vararg{<:Dimension}}

Swap dimensions for the passed in dimensions, in the order passed.

Passing in the Dimension types rewraps the dimension index, keeping the index values and metadata, while constructed Dimension objectes replace the original dimension. nothing leaves the original dimension as-is.

Arguments

• x: any object with a dims method or a Tuple of Dimension.
• newdim: Tuple of Dimension or dimension Type.

Example

using DimensionalData
A = ones(X(2), Y(4), Z(2))
Dimensions.swapdims(A, (Dim{:a}, Dim{:b}, Dim{:c}))

# output
2×4×2 DimArray{Float64,3} with dimensions: Dim{:a}, Dim{:b}, Dim{:c}
[:, :, 1]
1.0  1.0  1.0  1.0
1.0  1.0  1.0  1.0
[and 1 more slices...]
source
DimensionalData.Dimensions.slicedimsFunction
slicedims(x, I) => Tuple{Tuple,Tuple}
slicedims(f, x, I) => Tuple{Tuple,Tuple}

Slice the dimensions to match the axis values of the new array.

All methods return a tuple conatining two tuples: the new dimensions, and the reference dimensions. The ref dimensions are no longer used in the new struct but are useful to give context to plots.

Called at the array level the returned tuple will also include the previous reference dims attached to the array.

Arguments

• f: a function getindex, view or dotview. This will be used for slicing getindex is the default if f is not included.
• x: An AbstractDimArray, Tuple of Dimension, or Dimension
• I: A tuple of Integer, Colon or AbstractArray
source
DimensionalData.Dimensions.comparedimsFunction
comparedims(A::AbstractDimArray...; kw...)
comparedims(A::Tuple...; kw...)
comparedims(a, b; kw...)

Check that dimensions or tuples of dimensions are the same, and return the first valid dimension. If AbstractDimArrays are passed as arguments their dimensions are compared.

Empty tuples and nothing dimension values are ignored, returning the Dimension value if it exists.

Keywords

These are all Bool flags:

• type: compare complete type, true by default.
• lookuptype: compare wrapped LookupArray type, false by default.
• length: compare lengths, true by default.
• ignore_length_one: ignore length 1 in comparisons, and return whichever dimension is not length 1, if any. This is useful in e.g. broadcasting comparisons. false by default.
• value: compare all values in each LookupArray are identical, false by default.
source
DimensionalData.Dimensions.otherdimsFunction
otherdims(x, lookup) => Tuple{Vararg{<:Dimension,N}}

Get the dimensions of an object not in lookup.

Arguments

• x: any object with a dims method, a Tuple of Dimension.
• lookup: Tuple or single Dimension or dimension Type.
• f: <: by default, but can be >: to match abstract types to concrete types.

A tuple holding the unmatched dimensions is always returned.

Example

julia> using DimensionalData, DimensionalData.Dimensions

julia> A = DimArray(ones(10, 10, 10), (X, Y, Z));

julia> otherdims(A, X)
Y, Z

julia> otherdims(A, (Y, Z))
X
source
DimensionalData.Dimensions.commondimsFunction
commondims([f], x, lookup) => Tuple{Vararg{<:Dimension}}

This is basically dims(x, lookup) where the order of the original is kept, unlike dims where the lookup tuple determines the order

Also unlike dims,commondims always returns a Tuple, no matter the input. No errors are thrown if dims are absent from either x or lookup.

f is <: by default, but can be >: to sort abstract types by concrete types.

julia> using DimensionalData, .Dimensions

julia> A = DimArray(ones(10, 10, 10), (X, Y, Z));

julia> commondims(A, X)
X

julia> commondims(A, (X, Z))
X, Z

julia> commondims(A, Ti)
()

source
DimensionalData.Dimensions.sortdimsFunction
sortdims([f], tosort, order) => Tuple

Sort dimensions tosort by order. Dimensions in order but missing from tosort are replaced with nothing.

tosort and order can be Tuples or Vectors or Dimension or dimension type. Abstract supertypes like TimeDim can be used in order.

f is <: by default, but can be >: to sort abstract types by concrete types.

source
DimensionalData.Dimensions.LookupArrays.basetypeofFunction
basetypeof(x) => Type

Get the "base" type of an object - the minimum required to define the object without it's fields. By default this is the full UnionAll for the type. But custom basetypeof methods can be defined for types with free type parameters.

In DimensionalData this is primariliy used for comparing Dimensions, where Dim{:x} is different from Dim{:y}.

source
DimensionalData.Dimensions.setdimsFunction
setdims(X, newdims) => AbstractArray
setdims(::Tuple, newdims) => Tuple{Vararg{<:Dimension,N}}

Replaces the first dim matching <: basetypeof(newdim) with newdim, and returns a new object or tuple with the dimension updated.

Arguments

• x: any object with a dims method, a Tuple of Dimension or a single Dimension.
• newdim: Tuple or single Dimension, Type or Symbol.

Example

using DimensionalData, DimensionalData.Dimensions, DimensionalData.LookupArrays
A = ones(X(10), Y(10:10:100))
B = setdims(A, Y(Categorical('a':'j'; order=ForwardOrdered())))
lookup(B, Y)
# output
Categorical{Char} ForwardOrdered
wrapping: 'a':1:'j'
source
DimensionalData.Dimensions.dimsmatchFunction
dimsmatch([f], dim, lookup) => Bool
dimsmatch([f], dims::Tuple, lookups::Tuple) => Bool

Compare 2 dimensions or Tuple of Dimension are of the same base type, or are at least rotations/transformations of the same type.

f is <: by default, but can be >: to match abstract types to concrete types.

source
DimensionalData.Dimensions.dimstrideFunction
dimstride(x, dim) => Int

Get the stride of the dimension relative to the other dimensions.

This may or may not be equal to the stride of the related array, although it will be for Array.

Arguments

• x is any object with a dims method, or a Tuple of Dimension.
• dim is a Dimension, Dimension type, or and Int. Using an Int is not type-stable.
source
DimensionalData.refdims_titleFunction
refdims_title(A::AbstractDimArray)
refdims_title(refdims::Tuple)
refdims_title(refdim::Dimension)

Generate a title string based on reference dimension values.

source
DimensionalData.rebuild_from_arraysFunction
rebuild_from_arrays(s::AbstractDimStack, das::NamedTuple{<:Any,<:Tuple{Vararg{<:AbstractDimArray}}}; kw...)

Rebuild an AbstractDimStack from a NamedTuple of AbstractDimArray and an existing stack.

Keywords

Keywords are simply the fields of the stack object:

• data
• dims
• refdims
• metadata
• layerdims
• layermetadata
source

# LookupArrays

DimensionalData.Dimensions.LookupArraysModule
LookupArrays

Module for LookupArrays and [Selector]s used in DimensionalData.jl

LookupArrays defines traits and AbstractArray wrappers that give specific behaviours for a lookup index when indexed with Selector.

For example, these allow tracking over array order so fast indexing works evne when the array is reversed.

To load LookupArrays types and methods into scope:

using DimensionalData
using .LookupArrays
source

## Selectors

DimensionalData.Dimensions.LookupArrays.SelectorType
Selector

Abstract supertype for all selectors.

Selectors are wrappers that indicate that passed values are not the array indices, but values to be selected from the dimension index, such as DateTime objects for a Ti dimension.

Selectors provided in DimensionalData are:

source
DimensionalData.Dimensions.LookupArrays.AtType
At <: IntSelector

At(x, atol, rtol)
At(x; atol=nothing, rtol=nothing)

Selector that exactly matches the value on the passed-in dimensions, or throws an error. For ranges and arrays, every intermediate value must match an existing value - not just the end points.

x can be any value or Vector of values.

atol and rtol are passed to isapprox. For Number rtol will be set to Base.rtoldefault, otherwise nothing, and wont be used.

Example

using DimensionalData

A = DimArray([1 2 3; 4 5 6], (X(10:10:20), Y(5:7)))
A[X(At(20)), Y(At(6))]

# output

5
source
DimensionalData.Dimensions.LookupArrays.NearType
Near <: IntSelector

Near(x)

Selector that selects the nearest index to x.

With Points this is simply the index values nearest to the x, however with Intervals it is the interval center nearest to x. This will be offset from the index value for Start and End loci.

Example

using DimensionalData

A = DimArray([1 2 3; 4 5 6], (X(10:10:20), Y(5:7)))
A[X(Near(23)), Y(Near(5.1))]

# output
4
source
DimensionalData.Dimensions.LookupArrays.BetweenType
Between <: ArraySelector

Between(a, b)

Depreciated: use a..b instead of Between(a, b). Other Interval objects from IntervalSets.jl, like OpenInterval(a, b) will also work, giving the correct open/closed boundaries.

Between will e removed in furture to avoid clashes with DataFrames.Between.

Selector that retreive all indices located between 2 values, evaluated with >= for the lower value, and < for the upper value. This means the same value will not be counted twice in 2 adjacent Between selections.

For Intervals the whole interval must be lie between the values. For Points the points must fall between the values. Different Sampling types may give different results with the same input - this is the intended behaviour.

Between for Irregular intervals is a little complicated. The interval is the distance between a value and the next (for Start locus) or previous (for End locus) value.

For Center, we take the mid point between two index values as the start and end of each interval. This may or may not make sense for the values in your indes, so use Between with Irregular Intervals(Center()) with caution.

Example

using DimensionalData

A = DimArray([1 2 3; 4 5 6], (X(10:10:20), Y(5:7)))
A[X(Between(15, 25)), Y(Between(4, 6.5))]

# output

1×2 DimArray{Int64,2} with dimensions:
X Sampled{Int64} 20:10:20 ForwardOrdered Regular Points,
Y Sampled{Int64} 5:6 ForwardOrdered Regular Points
5  6
20  4  5
source
DimensionalData.Dimensions.LookupArrays.ContainsType
Contains <: IntSelector

Contains(x)

Selector that selects the interval the value is contained by. If the interval is not present in the index, an error will be thrown.

Can only be used for Intervals or Categorical.

Example

using DimensionalData; const DD = DimensionalData
dims_ = X(10:10:20; sampling=DD.Intervals(DD.Center())),
Y(5:7; sampling=DD.Intervals(DD.Center()))
A = DimArray([1 2 3; 4 5 6], dims_)
A[X(Contains(8)), Y(Contains(6.8))]

# output
3
source
DimensionalData.Dimensions.LookupArrays.WhereType
Where <: ArraySelector

Where(f::Function)

Selector that filters a dimension lookup by any function that accepts a single value and returns a Bool.

Example

using DimensionalData

A = DimArray([1 2 3; 4 5 6], (X(10:10:20), Y(19:21)))
A[X(Where(x -> x > 15)), Y(Where(x -> x in (19, 21)))]

# output

1×2 DimArray{Int64,2} with dimensions:
X Sampled{Int64} Int64[20] ForwardOrdered Regular Points,
Y Sampled{Int64} Int64[19, 21] ForwardOrdered Regular Points
19  21
20   4   6
source
DimensionalData.Dimensions.LookupArrays.AllType
All <: Selector

All(selectors::Selector...)

Selector that combines the results of other selectors. The indices used will be the union of all result sorted in ascending order.

Example

using DimensionalData, Unitful

dimz = X(10.0:20:200.0), Ti(1u"s":5u"s":100u"s")
A = DimArray((1:10) * (1:20)', dimz)
A[X=All(At(10.0), At(50.0)), Ti=All(1u"s"..10u"s", 90u"s"..100u"s")]

# output

2×4 DimArray{Int64,2} with dimensions:
X Sampled{Float64} Float64[10.0, 50.0] ForwardOrdered Regular Points,
Ti Sampled{Quantity{Int64, 𝐓, Unitful.FreeUnits{(s,), 𝐓, nothing}}} Quantity{Int64, 𝐓, Unitful.FreeUnits{(s,), 𝐓, nothing}}[1 s, 6 s, 91 s, 96 s] ForwardOrdered Regular Points
1 s  6 s  91 s  96 s
10.0    1    2    19    20
50.0    3    6    57    60
source

Lookup properties:

DimensionalData.Dimensions.LookupArrays.boundsFunction
bounds(xs, [dims::Tuple]) => Tuple{Vararg{<:Tuple{T,T}}}
bounds(xs::Tuple) => Tuple{Vararg{<:Tuple{T,T}}}
bounds(x, dim) => Tuple{T,T}
bounds(dim::Union{Dimension,LookupArray}) => Tuple{T,T}

Return the bounds of all dimensions of an object, of a specific dimension, or of a tuple of dimensions.

dims can be a Dimension, a dimension type, or a tuple of either.

source
DimensionalData.Dimensions.LookupArrays.valFunction
val(x)
val(dims::Tuple) => Tuple

Return the contained value of a wrapper object.

dims can be Dimension, Dimension types, or Symbols for Dim{Symbol}.

Objects that don't define a val method are returned unaltered.

source
DimensionalData.Dimensions.LookupArrays.LookupArrayType
LookupArray

Types defining the behaviour of a lookup index, how it is plotted and how Selectors like Between work.

A LookupArray may be NoLookup indicating that the index is just the underlying array axis, Categorical for ordered or unordered categories, or a Sampled index for Points or Intervals.

source
DimensionalData.Dimensions.LookupArrays.AbstractSampledType
AbstractSampled <: Aligned

Abstract supertype for LookupArrays where the index is aligned with the array, and is independent of other dimensions. Sampled is provided by this package.

AbstractSampled must have order, span and sampling fields, or a rebuild method that accpts them as keyword arguments.

source
DimensionalData.Dimensions.LookupArrays.SampledType
Sampled <: AbstractSampled

Sampled(; data=AutoIndex(), order=AutoOrder(), span=AutoSpan(), sampling=Points(), metadata=NoMetadata())

A concrete implementation of the LookupArray AbstractSampled. It can be used to represent Points or Intervals.

Sampled is capable of representing gridded data from a wide range of sources, allowing correct bounds and Selectors for points or intervals of regular, irregular, forward and reverse indexes.

On AbstractDimArray construction, Sampled lookup is assigned for all lookups of AbstractRange not assigned to Categorical.

Arguments

• data: An AbstractVector of index values, matching the length of the curresponding array axis.
• order: Order) indicating the order of the index, AutoOrder by default, detected from the order of data to be ForwardOrdered, ReverseOrdered or Unordered. These can be provided explicitly if they are known and performance is important.
• span: indicates the size of intervals or distance between points, and will be set to Regular for AbstractRange and Irregular for AbstractArray, unless assigned manually.
• sampling: is assigned to Points, unless set to Intervals manually. Using Intervals will change the behaviour of bounds and Selectorss to take account for the full size of the interval, rather than the point alone.
• metadata: a Dict or Metadata wrapper that holds any metadata object adding more information about the array axis - useful for extending DimensionalData for specific contexts, like geospatial data in GeoData.jl. By default it is NoMetadata().

Example

Create an array with [Interval] sampling, and Regular span for a vector with known spacing.

We set the Locus of the Intervals to Start specifying that the index values are for the positions at the start of each interval.

using DimensionalData, DimensionalData.LookupArrays

x = X(Sampled(100:-20:10; sampling=Intervals(Start())))
y = Y(Sampled([1, 4, 7, 10]; span=Regular(3), sampling=Intervals(Start())))
A = ones(x, y)

# output
5×4 DimArray{Float64,2} with dimensions:
X Sampled{Int64} 100:-20:20 ReverseOrdered Regular Intervals,
Y Sampled{Int64} Int64[1, 4, 7, 10] ForwardOrdered Regular Intervals
1    4    7    10
100  1.0  1.0  1.0   1.0
80  1.0  1.0  1.0   1.0
60  1.0  1.0  1.0   1.0
40  1.0  1.0  1.0   1.0
20  1.0  1.0  1.0   1.0
source
DimensionalData.Dimensions.LookupArrays.AbstractCategoricalType
AbstractCategorical <: Aligned

LookupArrays where the values are categories.

Categorical is the provided concrete implementation. but this can easily be extended - all methods are defined for AbstractCategorical.

All AbstractCategorical must provide a rebuild method with data, order and metadata keyword arguments.

source
DimensionalData.Dimensions.LookupArrays.CategoricalType
Categorical <: AbstractCategorical

Categorical(o::Order)
Categorical(; order=Unordered())

An LookupArray where the values are categories.

This will be automatically assigned if the index contains AbstractString, Symbol or Char. Otherwise it can be assigned manually.

Order will be determined automatically where possible.

Arguments

• data: An AbstractVector of index values, matching the length of the curresponding array axis.
• order: Order) indicating the order of the index, AutoOrder by default, detected from the order of data to be ForwardOrdered, ReverseOrdered or Unordered. Can be provided if this is known and performance is important.
• metadata: a Dict or Metadata wrapper that holds any metadata object adding more information about the array axis - useful for extending DimensionalData for specific contexts, like geospatial data in GeoData.jl. By default it is NoMetadata().

Example

Create an array with [Interval] sampling.

using DimensionalData

ds = X(["one", "two", "three"]), Y([:a, :b, :c, :d])
A = DimArray(rand(3, 4), ds)
Dimensions.lookup(A)

# output

Categorical{String} String[one, two, three] Unordered,
Categorical{Symbol} Symbol[a, b, c, d] ForwardOrdered
source
DimensionalData.Dimensions.LookupArrays.TransformedType
Transformed <: Unaligned

Transformed(f, dim::Dimension; metadata=NoMetadata())

LookupArray that uses an affine transformation to convert dimensions from dims(lookup) to dims(array). This can be useful when the dimensions are e.g. rotated from a more commonly used axis.

Any function can be used to do the transformation, but transformations from CoordinateTransformations.jl may be useful.

Arguments

• f: transformation function
• dim: a dimension to transform to.

Keyword Arguments

• metdata:

Example

using DimensionalData, DimensionalData.LookupArrays, CoordinateTransformations

m = LinearMap([0.5 0.0; 0.0 0.5])
A = [1 2  3  4
5 6  7  8
9 10 11 12];
da = DimArray(A, (t1=Transformed(m, X), t2=Transformed(m, Y)))

da[X(At(6)), Y(At(2))]

# output
9
source
DimensionalData.Dimensions.LookupArrays.NoLookupType
NoLookup <: LookupArray

NoLookup()

A LookupArray that is identical to the array axis. Selectors can't be used on this lookup.

Example

Defining a DimArray without passing an index to the dimensions, it will be assigned NoLookup:

using DimensionalData

A = DimArray(rand(3, 3), (X, Y))
Dimensions.lookup(A)

# output

NoLookup, NoLookup

Which is identical to:

using .LookupArrays
A = DimArray(rand(3, 3), (X(NoLookup()), Y(NoLookup())))
Dimensions.lookup(A)

# output

NoLookup, NoLookup
source
DimensionalData.Dimensions.LookupArrays.AutoIndexType
AutoIndex

Detect a LookupArray index from the context. This is used in NoLookup to simply use the array axis as the index when the array is constructed, and in set to change the LookupArray type without changing the index values.

source

DimensionalData.Dimensions.LookupArrays.AbstractMetadataType
AbstractMetadata{X,T}

Abstract supertype for all metadata wrappers.

Metadata wrappers allow tracking the contents and origin of metadata. This can facilitate conversion between metadata types (for saving a file to a differenet format) or simply saving data back to the same file type with identical metadata.

Using a wrapper instead of Dict or NamedTuple also lets us pass metadata objects to set without ambiguity about where to put them.

source
DimensionalData.Dimensions.LookupArrays.NoMetadataType
NoMetadata <: AbstractMetadata

NoMetadata()

Indicates an object has no metadata. But unlike using nothing, get, keys and haskey will still work on it, get always returning the fallback argument. keys returns () while haskey always returns false.

source

## LookupArray traits

### Order

DimensionalData.Dimensions.LookupArrays.UnorderedType
Unordered <: Order

Unordered()

Indicates that LookupArray is unordered.

This means the index cannot be searched with searchsortedfirst or similar optimised methods - instead it will use findfirst.

source

### Span

DimensionalData.Dimensions.LookupArrays.IrregularType
Irregular <: Span

Irregular(bounds::Tuple)
Irregular(lowerbound, upperbound)

Points or Intervals that have an Irrigular step size. To enable bounds tracking and accuract selectors, the starting bounds are provided as a 2 tuple, or 2 arguments. (nothing, nothing) is acceptable input, the bounds will be guessed from the index, but may be innaccurate.

source

### Loci

DimensionalData.Dimensions.LookupArrays.LocusType

Locus <: LookupArrayTrait

Abstract supertype of types that indicate the position of index values where they represent Intervals.

These allow for values array cells to align with the Start, Center, or End of values in the lookup index.

This means they can be plotted with correct axis markers, and allows automatic converrsions to between formats with different standards (such as NetCDF and GeoTiff).

source

## LookupArrays methods

DimensionalData.Dimensions.LookupArrays.hasselectionFunction
hasselection(x, selector) => Bool
hasselection(x, selectors::Tuple) => Bool

Check if indexing into x with selectors can be performed, where x is some object with a dims method, and selectors is a Selector or Dimension or a tuple of either.

source
DimensionalData.Dimensions.LookupArrays.samplingFunction
sampling(x, [dims::Tuple]) => Tuple
sampling(x, dim) => Sampling
sampling(xs::Tuple) => Tuple{Vararg{<:Sampling}}
sampling(x:Union{Dimension,LookupArray}) => Sampling

Return the Sampling for each dimension.

Second argument dims can be Dimensions, Dimension types, or Symbols for Dim{Symbol}.

source
DimensionalData.Dimensions.LookupArrays.spanFunction
span(x, [dims::Tuple]) => Tuple
span(x, dim) => Span
span(xs::Tuple) => Tuple{Vararg{<:Span,N}}
span(x::Union{Dimension,LookupArray}) => Span

Return the Span for each dimension.

Second argument dims can be Dimensions, Dimension types, or Symbols for Dim{Symbol}.

source
DimensionalData.Dimensions.LookupArrays.orderFunction
order(x, [dims::Tuple]) => Tuple
order(xs::Tuple) => Tuple
order(x::Union{Dimension,LookupArray}) => Order

Return the Ordering of the dimension index for each dimension: ForwardOrdered, ReverseOrdered, or Unordered

Second argument dims can be Dimensions, Dimension types, or Symbols for Dim{Symbol}.

source
DimensionalData.Dimensions.LookupArrays.indexFunction
index(x) => Tuple{Vararg{<:AbstractArray}}
index(x, dims::Tuple) => Tuple{Vararg{<:AbstractArray}}
index(dims::Tuple) => Tuple{Vararg{<:AbstractArray}}}
index(x, dim) => AbstractArray
index(dim::Dimension) => AbstractArray

Return the contained index of a Dimension.

Only valid when a Dimension contains an AbstractArray or a Val tuple like Val{(:a, :b)}(). The Val is unwrapped to return just the Tuple

dims can be a Dimension, or a tuple of Dimension.

source
DimensionalData.Dimensions.LookupArrays.locusFunction
locus(x, [dims::Tuple]) => Tuple
locus(x, dim) => Locus
locus(xs::Tuple) => Tuple{Vararg{<:Locus,N}}
locus(x::Union{Dimension,LookupArray}) => Locus

Return the Locus for each dimension.

Second argument dims can be Dimensions, Dimension types, or Symbols for Dim{Symbol}.

source
DimensionalData.Dimensions.LookupArrays.unitsFunction
units(x) => Union{Nothing,Any}
units(xs:Tuple) => Tuple
unit(A::AbstractDimArray, dims::Tuple) => Tuple
unit(A::AbstractDimArray, dim) => Union{Nothing,Any}

Get the units of an array or Dimension, or a tuple of of either.

Units do not have a set field, and may or may not be included in metadata. This method is to facilitate use in labels and plots when units are available, not a guarantee that they will be. If not available, nothing is returned.

Second argument dims can be Dimensions, Dimension types, or Symbols for Dim{Symbol}.

source

## Name

DimensionalData.NameType
Name <: AbstractName

Name(name::Union{Symbol,Name) => Name
Name(name::NoName) => NoName

Name wrapper. This lets arrays keep symbol names when the array wrapper neeeds to be isbits, like for use on GPUs. It makes the name a property of the type. It's not necessary to use in normal use, a symbol is probably easier.

source
DimensionalData.NoNameType
NoName <: AbstractName

NoName()

NoName specifies an array is not named, and is the default name value for all AAbstractDimArray`s.

source