-
Notifications
You must be signed in to change notification settings - Fork 41
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* update docs template * setup
- Loading branch information
Showing
14 changed files
with
1,057 additions
and
677 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
name: Documenter | ||
on: | ||
push: | ||
branches: [main] | ||
tags: [v*] | ||
pull_request: | ||
branches: [main] | ||
concurrency: | ||
# Skip intermediate builds: always. | ||
# Cancel intermediate builds: only if it is a pull request build. | ||
group: ${{ github.workflow }}-${{ github.ref }} | ||
cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }} | ||
jobs: | ||
build: | ||
permissions: | ||
contents: write | ||
runs-on: ubuntu-latest | ||
steps: | ||
- uses: actions/checkout@v3 | ||
- uses: julia-actions/setup-julia@v1 | ||
- uses: julia-actions/cache@v1 | ||
with: | ||
cache-registries: "true" | ||
- name: Install documentation dependencies | ||
run: julia --project=docs -e 'using Pkg; pkg"dev ."; Pkg.instantiate()' | ||
- name: Build and deploy | ||
env: | ||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token | ||
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key | ||
GKSwstype: "100" # https://discourse.julialang.org/t/generation-of-documentation-fails-qt-qpa-xcb-could-not-connect-to-display/60988 | ||
JULIA_DEBUG: "Documenter" | ||
DATADEPS_ALWAYS_ACCEPT: true | ||
run: | | ||
julia --code-coverage=user --project=docs/ --color=yes docs/genfiles.jl | ||
julia --code-coverage=user --project=docs/ --color=yes docs/make.jl |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,9 @@ | ||
[deps] | ||
BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf" | ||
CoordinateTransformations = "150eb455-5306-5404-9cee-2592286d6298" | ||
Dates = "ade2ca70-3891-5945-98fb-dc099432e06a" | ||
DimensionalData = "0703355e-b756-11e9-17c0-8b28908087d0" | ||
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" | ||
Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c" | ||
DocumenterMarkdown = "997ab1e6-3595-5248-9280-8efb232c3433" | ||
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" | ||
Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
{% import "partials/language.html" as lang with context %} | ||
<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source" data-md-component="source"> | ||
<div class="md-source__icon md-icon"> | ||
{% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %} | ||
{% include ".icons/" ~ icon ~ ".svg" %} | ||
</div> | ||
<div class="md-source__repository"> | ||
{{ config.repo_name }} | ||
</div> | ||
</a> | ||
{% if config.theme.twitter_url %} | ||
<a href="{{ config.theme.twitter_url }}" title="Go to Twitter" class="md-source"> | ||
<div class="md-source__icon md-icon"> | ||
{% include ".icons/fontawesome/brands/twitter.svg" %} | ||
</div> | ||
<div class="md-source__repository"> | ||
{{ config.theme.twitter_name }} | ||
</div> | ||
</a> | ||
{% endif %} | ||
{% if config.theme.sponsor_url %} | ||
<a href="{{ config.theme.sponsor_url }}" title="Go to Sponsor" class="md-source"> | ||
<div class="md-source__icon md-icon"> | ||
{% include ".icons/fontawesome/regular/heart.svg" %} | ||
</div> | ||
<div class="md-source__repository"> | ||
{{ config.theme.sponsor_name }} | ||
</div> | ||
</a> | ||
{% endif %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,283 @@ | ||
using DimensionalData | ||
|
||
# ## Dimensions and DimArrays | ||
|
||
# The core type of DimensionalData.jl is the [`Dimension`](@ref) and the types | ||
# that inherit from it, such as `Ti`, `X`, `Y`, `Z`, the generic `Dim{:x}`, or | ||
# others that you define manually using the [`@dim`](@ref) macro. | ||
|
||
# `Dimension`s are primarily used in [`DimArray`](@ref), other | ||
# [`AbstractDimArray`](@ref). | ||
|
||
# We can use dimensions without a value index - these simply label the axis. | ||
# A `DimArray` with labelled dimensions is constructed by: | ||
|
||
using DimensionalData | ||
A = rand(X(5), Y(5)) | ||
|
||
# get value | ||
|
||
A[Y(1), X(2)] | ||
|
||
# As shown above, `Dimension`s can be used to construct arrays in `rand`, `ones`, | ||
# `zeros` and `fill` with either a range for a lookup index or a number for the | ||
# dimension length. | ||
|
||
# Or we can use the `Dim{X}` dims by using `Symbol`s, and indexing with keywords: | ||
|
||
A = DimArray(rand(5, 5), (:a, :b)) | ||
|
||
# get value | ||
|
||
A[a=3, b=5] | ||
|
||
# Often, we want to provide a lookup index for the dimension: | ||
|
||
using Dates | ||
t = DateTime(2001):Month(1):DateTime(2001,12) | ||
x = 10:10:100 | ||
A = rand(X(x), Ti(t)) | ||
|
||
# Here both `X` and `Ti` are dimensions from `DimensionalData`. The currently | ||
# exported dimensions are `X, Y, Z, Ti` (`Ti` is shortening of `Time`). | ||
|
||
# The length of each dimension index has to match the size of the corresponding | ||
# array axis. | ||
|
||
# This can also be done with `Symbol`, using `Dim{X}`: | ||
|
||
A2 = DimArray(rand(12, 10), (time=t, distance=x)) | ||
|
||
# Symbols can be more convenient to use than defining custom dims with `@dim`, but | ||
# have some downsides. They don't inherit from a specific `Dimension` type, so | ||
# plots will not know what axis to put them on. They also cannot use the basic | ||
# constructor methods like `rand` or `zeros`, as we cannot dispatch on `Symbol` | ||
# for Base methods without "type-piracy". | ||
|
||
|
||
# ## Indexing the array by name and index | ||
|
||
# Dimensions can be used to index the array by name, without having to worry | ||
# about the order of the dimensions. | ||
|
||
# The simplest case is to select a dimension by index. Let's say every 2nd point | ||
# of the `Ti` dimension and every 3rd point of the `X` dimension. This is done | ||
# with the simple `Ti(range)` syntax like so: | ||
|
||
A[X(1:3:11), Ti(1:2:11)] | ||
|
||
# When specifying only one dimension, all elements of the other | ||
# dimensions are assumed to be included: | ||
|
||
A[X(1:3:10)] | ||
|
||
# !!! info "Indexing" | ||
# Indexing `AbstractDimArray`s works with `getindex`, `setindex!` and | ||
# `view`. The result is still an `AbstracDimArray`, unless using all single | ||
# `Int` or `Selector`s that resolve to `Int`. | ||
|
||
|
||
# `Dimension`s can be used to construct arrays in `rand`, `ones`, `zeros` and | ||
# `fill` with either a range for a lookup index or a number for the dimension | ||
# length. | ||
|
||
using DimensionalData | ||
A1 = ones(X(1:40), Y(50)) | ||
|
||
# We can also use dim wrappers for indexing, so that the dimension order in the underlying array | ||
# does not need to be known: | ||
|
||
A1[Y(1), X(1:10)] | ||
|
||
|
||
# ## Indexing Performance | ||
|
||
# Indexing with `Dimension` has no runtime cost: | ||
|
||
A2 = ones(X(3), Y(3)) | ||
|
||
# time ? | ||
using BenchmarkTools | ||
|
||
println(@btime $A2[X(1), Y(2)]) | ||
|
||
# and | ||
|
||
println(@btime parent($A2)[1, 2]) | ||
|
||
# ## Specifying `dims` keyword arguments with `Dimension` | ||
|
||
# In many Julia functions like `size` or `sum`, you can specify the dimension | ||
# along which to perform the operation as an `Int`. It is also possible to do this | ||
# using [`Dimension`](@ref) types with `AbstractDimArray`: | ||
|
||
A3 = rand(X(3), Y(4), Ti(5)); | ||
sum(A3; dims=Ti) | ||
|
||
# This also works in methods from `Statistics`: | ||
|
||
using Statistics | ||
mean(A3; dims=Ti) | ||
|
||
# ## Methods where dims, dim types, or `Symbol`s can be used to indicate the array dimension: | ||
|
||
# - `size`, `axes`, `firstindex`, `lastindex` | ||
# - `cat`, `reverse`, `dropdims` | ||
# - `reduce`, `mapreduce` | ||
# - `sum`, `prod`, `maximum`, `minimum`, | ||
# - `mean`, `median`, `extrema`, `std`, `var`, `cor`, `cov` | ||
# - `permutedims`, `adjoint`, `transpose`, `Transpose` | ||
# - `mapslices`, `eachslice` | ||
|
||
# ## LookupArrays and Selectors | ||
|
||
# Indexing by value in `DimensionalData` is done with [Selectors](@ref). | ||
# IntervalSets.jl is now used for selecting ranges of values (formerly `Between`). | ||
|
||
# | Selector | Description | | ||
# | :---------------------- | :------------------------------------------------------------------ | | ||
# | [`At(x)`](@ref) | get the index exactly matching the passed in value(s) | | ||
# | [`Near(x)`](@ref) | get the closest index to the passed in value(s) | | ||
# | [`Contains(x)`](@ref) | get indices where the value x falls within an interval | | ||
# | [`Where(f)`](@ref) | filter the array axis by a function of the dimension index values. | | ||
# | [`a..b`] | get all indices between two values, inclusively. | | ||
# | [`OpenInterval(a, b)`] | get all indices between `a` and `b`, exclusively. | | ||
# | [`Interval{A,B}(a, b)`] | get all indices between `a` and `b`, as `:closed` or `:open`. | | ||
|
||
|
||
# Selectors find indices in the `LookupArray`, for each dimension. | ||
# Here we use an `Interval` to select a range between integers and `DateTime`: | ||
|
||
A[X(12..35), Ti(Date(2001, 5)..Date(2001, 7))] | ||
|
||
|
||
# Selectors can be used in `getindex`, `setindex!` and | ||
# `view` to select indices matching the passed in value(s) | ||
|
||
# We can use selectors inside dim wrappers, here selecting values from `DateTime` and `Int`: | ||
|
||
using Dates | ||
timespan = DateTime(2001,1):Month(1):DateTime(2001,12) | ||
A4 = rand(Ti(timespan), X(10:10:100)) | ||
A4[X(Near(35)), Ti(At(DateTime(2001,5)))] | ||
|
||
# Without dim wrappers selectors must be in the right order, and specify all axes: | ||
|
||
using Unitful | ||
A5 = rand(Y((1:10:100)u"m"), Ti((1:5:100)u"s")); | ||
A5[10.5u"m" .. 50.5u"m", Near(23u"s")] | ||
|
||
|
||
# We can also use Linear indices as in standard `Array`: | ||
|
||
A5[1:5] | ||
|
||
# But unless the `DimArray` is one dimensional, this will return a regular | ||
# `Array`. It is not possible to keep the `LookupArray` or even `Dimension`s after | ||
# linear indexing is used. | ||
|
||
# ## LookupArrays and traits | ||
|
||
# Using a regular range or `Vector` as a lookup index has a number of downsides. | ||
# We cannot use `searchsorted` for fast searches without knowing the order of the | ||
# array, and this is slow to compute at runtime. It also means `reverse` or | ||
# rotations cannot be used while keeping the `DimArray` wrapper. | ||
|
||
# Step sizes are also a problem. Some ranges like `LinRange` lose their step size | ||
# with a length of `1`. Often, instead of a range, multi-dimensional data formats | ||
# provide a `Vector` of evenly spaced values for a lookup, with a step size | ||
# specified separately. Converting to a range introduces floating point errors | ||
# that means points may not be selected with `At` without setting tolerances. | ||
|
||
# This means using a lookup wrapper with traits is more generally robust and | ||
# versatile than simply using a range or vector. DimensionalData provides types | ||
# for specifying details about the dimension index, in the [`LookupArrays`](@ref) | ||
# sub-module: | ||
|
||
using DimensionalData | ||
using .LookupArrays | ||
|
||
# The main [`LookupArray`](@ref) are : | ||
|
||
# - [`Sampled`](@ref) | ||
# - [`Categorical`](@ref), | ||
# - [`NoLookup`](@ref) | ||
|
||
# Each comes with specific traits that are either fixed or variable, depending | ||
# on the contained index. These enable optimisations with `Selector`s, and modified | ||
# behaviours, such as: | ||
|
||
# 1. Selection of [`Intervals`](@ref) or [`Points`](@ref), which will give slightly | ||
# different results for selectors like `..` - as whole intervals are | ||
# selected, and have different `bounds` values. | ||
|
||
# 2. Tracking of lookup order. A reverse order is labelled `ReverseOrdered` and | ||
# will still work with `searchsorted`, and for plots to always be the right way | ||
# up when either the index or the array is backwards. Reversing a `DimArray` | ||
# will reverse the `LookupArray` for that dimension, swapping `ReverseOrdered` | ||
# to `ForwardOrdered`. | ||
|
||
# 3. `Sampled` [`Intervals`](@ref) can have index located at a [`Locus`](@ref) of: | ||
|
||
# - [`Start`](@ref), | ||
# - [`Center`](@ref) | ||
# - [`End`](@ref) | ||
|
||
# Which specifies the point of the interval represented in the index, to match | ||
# different data standards, e.g. GeoTIFF (`Start`) and NetCDF (`Center`). | ||
|
||
# 4. A [`Span`](@ref) specifies the gap between `Points` or the size of | ||
# `Intervals`. This may be: | ||
|
||
# - [`Regular`](@ref), in the case of a range and equally spaced vector, | ||
# - [`Irregular`](@ref) for unequally spaced vectors | ||
# - [`Explicit`](@ref) for the case where all interval start and end points are | ||
# specified explicitly - as is common in the NetCDF standard. | ||
|
||
# These traits all for subtypes of [`Aligned`](@ref). | ||
|
||
# [`Unaligned`](@ref) also exists to handle dimensions with an index that is | ||
# rotated or otherwise transformed in relation to the underlying array, such as | ||
# [`Transformed`](@ref). | ||
|
||
|
||
# ## LookupArray detection | ||
|
||
# [`Aligned`](@ref) types will be detected automatically if not specified - which | ||
# usually isn't required. | ||
|
||
# - An empty `Dimension` or a `Type` or `Symbol` will be assigned `NoLookup` - | ||
# this behaves as a simple named dimension without a lookup index. | ||
# - A `Dimension` containing and index of `String`, `Char`, `Symbol` or mixed | ||
# types will be given the [`Categorical`](@ref) mode, | ||
# - A range will be assigned [`Sampled`](@ref), defaulting to | ||
# [`Regular`](@ref), [`Points`](@ref) | ||
# - Other `AbstractVector` will be assigned [`Sampled`](@ref) [`Irregular`](@ref) | ||
# [`Points`](@ref). | ||
|
||
# In all cases the [`Order`](@ref) of [`ForwardOrdered`](@ref) or | ||
# [`ReverseOrdered`](@ref) will be be detected, otherwise [`Unordered`](@ref) | ||
# for an unsorted `Array`. | ||
|
||
# See the [`LookupArray`](@ref) API docs for more detail. | ||
|
||
# ## Referenced dimensions | ||
|
||
# The reference dimensions record the previous dimensions that an array was | ||
# selected from. These can be use for plot labelling, and tracking array changes | ||
# so that `cat` can reconstruct the lookup array from previous dimensions that | ||
# have been sliced. | ||
|
||
# ## Warnings | ||
|
||
# Indexing with unordered or reverse-ordered arrays has undefined behaviour. | ||
# It will trash the dimension index, break `searchsorted` and nothing will make | ||
# sense any more. So do it at you own risk. | ||
|
||
# However, indexing with sorted vectors of `Int` can be useful, so it's allowed. | ||
# But it may do strange things to interval sizes for [`Intervals`](@ref) that are | ||
# not [`Explicit`](@ref). | ||
|
||
# This selects the first 5 entries of the underlying array. In the case that `A` | ||
# has only one dimension, it will be retained. Multidimensional `AbstracDimArray` | ||
# indexed this way will return a regular array. |
Oops, something went wrong.