Dimensions

Dimensions are kept in the sub-module Dimensions.

DimensionalData.Dimensions Module

Dimensions

Sub-module for Dimensions wrappers, and operations on them used in DimensionalData.jl.

To load Dimensions types and methods into scope:

using DimensionalData
using DimensionalData.Dimensions

source

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

DimensionalData.Dimensions.Dimension Type

Dimension

Abstract supertype of all dimension types.

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

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

They may also wrap lookup values for each array axis. This may be any AbstractVector matching the array axis length, but will usually be converted to a Lookup when use in a constructed object.

A 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} ┐
├─────────────────────────────┴────────────────────────────────────────── dims ┐
  ↓ Y  Categorical{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

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} ┐
├─────────────────────────────────┴────────────────────────────────────── dims ┐
  ↓ Ti Sampled{DateTime} DateTime("2021-01-01T00:00:00"):Month(1):DateTime("2021-12-01T00:00:00") 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} ┐
├───────────────────────────┴──────────────────────────────────────────── dims ┐
  ↓ 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
└──────────────────────────────────────────────────────────────────────────────┘
 ↓ →   2021-01-01T00:00:00   2021-02-01T00:00:00  …   2021-12-01T00:00:00
 4    0.0                   0.0                      0.0

source

DimensionalData.Dimensions.DependentDim Type

DependentDim <: Dimension

Abstract supertype for dependent dimensions. These will plot on the Y axis.

source

DimensionalData.Dimensions.IndependentDim Type

IndependentDim <: Dimension

Abstract supertype for independent dimensions. These will plot on the X axis.

source

DimensionalData.Dimensions.XDim Type

XDim <: IndependentDim

Abstract supertype for all X dimensions.

source

DimensionalData.Dimensions.YDim Type

YDim <: DependentDim

Abstract supertype for all Y dimensions.

source

DimensionalData.Dimensions.ZDim Type

ZDim <: DependentDim

Abstract supertype for all Z dimensions.

source

DimensionalData.Dimensions.TimeDim Type

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.X Type

X <: XDim

X(val=:)

X Dimension. X <: XDim <: IndependentDim

Examples

xdim = X(2:2:10)

val = A[X(1)]

mean(A; dims=X)

source

DimensionalData.Dimensions.Y Type

Y <: YDim

Y(val=:)

Y Dimension. Y <: YDim <: DependentDim

Examples

ydim = Y(['a', 'b', 'c'])

val = A[Y(1)]

mean(A; dims=Y)

source

DimensionalData.Dimensions.Z Type

Z <: ZDim

Z(val=:)

Z Dimension. Z <: ZDim <: Dimension

Example:

zdim = Z(10:10:100)

val = A[Z(1)]

mean(A; dims=Z)

source

DimensionalData.Dimensions.Ti Type

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))

val = A[Ti(1)]

mean(A; dims=Ti)

source

DimensionalData.Dimensions.Dim Type

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.

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

source

DimensionalData.Dimensions.AnonDim Type

AnonDim <: Dimension

AnonDim()

Anonymous dimension. Used when extra dimensions are created, such as during transpose of a vector.

source

DimensionalData.Dimensions.@dim Macro

@dim typ [supertype=Dimension] [label::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 Dimension 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.

label is used in plots and similar, if the dimension is short for a longer word.

Example:

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

source

Exported methods

These are widely useful methods for working with dimensions.

DimensionalData.Dimensions.dims Function

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

dims(x, query) => Tuple{Vararg{Dimension}}
dims(x, query...) => Tuple{Vararg{Dimension}}

Get the dimension(s) matching the type(s) of the query dimension.

Lookup can be an Int or an Dimension, or a tuple containing any combination of either.

Arguments

• x: any object with a dims method, or a Tuple of Dimension.

• query: Tuple or a single Dimension or Dimension Type.

Example

julia> using DimensionalData

julia> A = DimArray(ones(2, 3, 2), (X, Y, Z))
┌ 2×3×2 DimArray{Float64, 3} ┐
├────────────────────── dims ┤
  ↓ X, → Y, ↗ Z
└────────────────────────────┘
[:, :, 1]
 1.0  1.0  1.0
 1.0  1.0  1.0

julia> dims(A, (X, Y))
(↓ X, → Y)

source

DimensionalData.Dimensions.otherdims Function

otherdims(x, query) => Tuple{Vararg{Dimension,N}}

Get the dimensions of an object not in query.

Arguments

• x: any object with a dims method, a Tuple of Dimension.

• query: 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.dimnum Function

dimnum(x, query::Tuple) => NTuple{Int}
dimnum(x, query) => 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.

• query: Tuple, Array or single Dimension or dimension Type.

The return type will be a Tuple of Int or a single Int, depending on whether query 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

DimensionalData.Dimensions.hasdim Function

hasdim([f], x, query::Tuple) => NTuple{Bool}
hasdim([f], x, query...) => NTuple{Bool}
hasdim([f], x, query) => Bool

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

Arguments

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

• query: 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

Non-exported methods

DimensionalData.Dimensions.lookup Function

lookup(x::Dimension) => Lookup
lookup(x, [dims::Tuple]) => Tuple{Vararg{Lookup}}
lookup(x::Tuple) => Tuple{Vararg{Lookup}}
lookup(x, dim) => Lookup

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

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

This is separate from val in that it will only work when dimensions actually contain an AbstractArray lookup, and can be used on a DimArray or DimStack to retrieve all lookups, as there is no ambiguity of meaning as there is with val.

source

DimensionalData.Dimensions.label Function

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.format Function

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 Lookup hasn't been specified, a lookup is chosen based on the type and element type of the values.

source

DimensionalData.Dimensions.dims2indices Function

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.Lookups.selectindices Function

selectindices(lookups, selectors)

Converts Selector to regular indices.

source

Primitive methods

These low-level methods are really for internal use, but can be useful for writing dimensional algorithms.

They are not guaranteed to keep their interface, but usually will.

DimensionalData.Dimensions.commondims Function

commondims([f], x, query) => Tuple{Vararg{Dimension}}

This is basically dims(x, query) where the order of the original is kept, unlike dims where the query 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 query.

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.name2dim Function

name2dim(s::Symbol) => Dimension
name2dim(dims...) => Tuple{Dimension,Vararg}
name2dim(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.reducedims Function

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.

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

source

DimensionalData.Dimensions.swapdims Function

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 objects 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} ┐
├────────────────────── dims ┤
  ↓ a, → b, ↗ c
└────────────────────────────┘
[:, :, 1]
 1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0

source

DimensionalData.Dimensions.slicedims Function

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 containing 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.comparedims Function

comparedims(A::AbstractDimArray...; kw...)
comparedims(A::Tuple...; kw...)
comparedims(A::Dimension...; kw...)
comparedims(::Type{Bool}, args...; kw...)

Check that dimensions or tuples of dimensions passed as each argument 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.

Passing Bool as the first argument means true/false will be returned, rather than throwing an error.

Keywords

These are all Bool flags:

• type: compare dimension type, true by default.

• valtype: compare wrapped value type, false by default.

• val: compare wrapped values, false by default.

• order: compare order, 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.

• msg: DimensionalData.Warn or DimensionalData.Throw. Both may contain string, which will be added to error or warning mesages.

source

DimensionalData.Dimensions.combinedims Function

combinedims(xs; check=true, kw...)

Combine the dimensions of each object in xs, in the order they are found.

Keywords are passed to comparedims.

source

DimensionalData.Dimensions.sortdims Function

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.Lookups.basetypeof Function

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 primarily used for comparing Dimensions, where Dim{:x} is different from Dim{:y}.

source

DimensionalData.Dimensions.basedims Function

basedims(ds::Tuple)
basedims(d::Union{Dimension,Symbol,Type})

Returns basetypeof(d)() or a Tuple of called on a Tuple.

See basetypeof

source

DimensionalData.Dimensions.setdims Function

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.Lookups
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.dimsmatch Function

dimsmatch([f], dim, query) => Bool
dimsmatch([f], dims::Tuple, query::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