Getting Started

Installation

Install Julia v1.10 or above. YAXArrays.jl is available through the Julia package manager. You can enter it by pressing ] in the REPL and then typing

pkg> add YAXArrays

Alternatively, you can also do

import Pkg; Pkg.add("YAXArrays")

Quickstart

Create a simple array from random numbers given the size of each dimension or axis:

using YAXArrays
using YAXArrays: YAXArrays as YAX

a = YAXArray(rand(2,3))

┌ 2×3 YAXArray{Float64, 2} ┐
├──────────────────────────┴──────────────────────────────────── dims ┐
  ↓ Dim_1 Sampled{Int64} Base.OneTo(2) ForwardOrdered Regular Points,
  → Dim_2 Sampled{Int64} Base.OneTo(3) ForwardOrdered Regular Points
├─────────────────────────────────────────────────────────── metadata ┤
  Dict{String, Any}()
├─────────────────────────────────────────────────── loaded in memory ┤
  data size: 48.0 bytes
└─────────────────────────────────────────────────────────────────────┘

Assemble a more complex YAXArray with 4 dimensions, i.e. time, x, y and a variable type:

# axes or dimensions with name and tick values
axlist = (
    YAX.time(range(1, 20, length=20)),
    lon(range(1, 10, length=10)),
    lat(range(1, 5, length=15)),
    Variables(["temperature", "precipitation"])
)

# the actual data matching the dimensions defined in axlist
data = rand(20, 10, 15, 2)

# metadata about the array
props = Dict(
    "origin" => "YAXArrays.jl example",
    "x" => "longitude",
    "y" => "latitude",
);

a2 = YAXArray(axlist, data, props)

┌ 20×10×15×2 YAXArray{Float64, 4} ┐
├─────────────────────────────────┴────────────────────────────────────── dims ┐
  ↓ time      Sampled{Float64} 1.0:1.0:20.0 ForwardOrdered Regular Points,
  → lon       Sampled{Float64} 1.0:1.0:10.0 ForwardOrdered Regular Points,
  ↗ lat       Sampled{Float64} 1.0:0.2857142857142857:5.0 ForwardOrdered Regular Points,
  ⬔ Variables Categorical{String} ["temperature", "precipitation"] ReverseOrdered
├──────────────────────────────────────────────────────────────────── metadata ┤
  Dict{String, String} with 3 entries:
  "y"      => "latitude"
  "x"      => "longitude"
  "origin" => "YAXArrays.jl example"
├──────────────────────────────────────────────────────────── loaded in memory ┤
  data size: 46.88 KB
└──────────────────────────────────────────────────────────────────────────────┘

Get the temperature map at the first point in time:

a2[Variables=At("temperature"), time=1].data

10×15 view(::Array{Float64, 4}, 1, :, :, 1) with eltype Float64:
 0.320052  0.500909   0.827727   0.415137  …  0.825496  0.487315  0.0962708
 0.209357  0.0833026  0.207967   0.224959     0.309666  0.211397  0.552582
 0.507229  0.757781   0.514759   0.973442     0.111379  0.787476  0.0247931
 0.879677  0.374138   0.97643    0.748725     0.665274  0.776172  0.666534
 0.79472   0.958973   0.0114824  0.274902     0.499743  0.645512  0.622774
 0.320869  0.952795   0.547668   0.982108  …  0.80871   0.253383  0.743343
 0.496429  0.0436     0.790617   0.233118     0.137114  0.55245   0.716721
 0.683599  0.598769   0.0571978  0.155874     0.623962  0.959705  0.957463
 0.179919  0.551487   0.783779   0.828388     0.303359  0.542756  0.903079
 0.487093  0.78064    0.191898   0.908084     0.60764   0.833498  0.198806

Updates

TIP

The Julia Compiler is always improving. As such, we recommend using the latest stable version of Julia.

You may check the installed version with:

pkg> st YAXArrays

INFO

With YAXArrays.jl 0.5 we switched the underlying data type to be a subtype of the DimensionalData.jl types. Therefore the indexing with named dimensions changed to the DimensionalData syntax. See the DimensionalData.jl docs.