Merge branch 'master' into axes

Author: mcabbott

.github/workflows/CompatHelper.yml

@@ -0,0 +1,25 @@
+name: CompatHelper
+
+on:
+  schedule:
+    - cron: '00 * * * *'
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        julia-version: [1.2.0]
+        julia-arch: [x86]
+        os: [ubuntu-latest]
+    steps:
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: ${{ matrix.julia-version }}
+      - name: Install dependencies
+        run: julia -e 'using Pkg; Pkg.add(Pkg.PackageSpec(name = "CompatHelper", url = "https://github.com/bcbi/CompatHelper.jl.git"))'
+      - name: CompatHelper.main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          JULIA_DEBUG: CompatHelper
+        run: julia -e 'using CompatHelper; CompatHelper.main()'

.github/workflows/TagBot.yml

@@ -0,0 +1,11 @@
+name: TagBot
+on:
+  schedule:
+    - cron: 0 * * * *
+jobs:
+  TagBot:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

Project.toml

@@ -1,28 +1,33 @@
 name = "AxisKeys"
 uuid = "94b1ba4f-4ee9-5380-92f1-94cde586c3c5"
 license = "MIT"
-version = "0.0.1"
+version = "0.0.2"
 
 [deps]
 IntervalSets = "8197267c-284f-5f27-9208-e0e47529a953"
-LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+InvertedIndices = "41ab1584-1d38-5bbf-9106-f11c6c58b48f"
 LazyStack = "1fad7336-0346-5a1a-a56f-a06ba010965b"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 NamedDims = "356022a1-0364-5f58-8944-0da4b18d706f"
 OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 
 [compat]
+BenchmarkTools = "0.5"
 IntervalSets = "0.3, 0.4"
-NamedDims = "0.2.18"
-LazyStack = "0.0.7"
-OffsetArrays = "0.10, 0.11"
+InvertedIndices = "1.0"
+LazyStack = "0.0.7, 0.0.8"
+NamedDims = "0.2.20"
+OffsetArrays = "0.10, 0.11, 1.0"
 Tables = "0.2, 1"
 julia = "1"
 
 [extras]
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 UniqueVectors = "2fbcfb34-fd0c-5fbb-b5d7-e826d8f5b0a9"
 
 [targets]
-test = ["Test", "UniqueVectors"]
+test = ["BenchmarkTools", "Dates", "Test", "UniqueVectors"]

README.md

@@ -2,27 +2,27 @@
 
 [![Build Status](https://travis-ci.org/mcabbott/AxisKeys.jl.svg?branch=master)](https://travis-ci.org/mcabbott/AxisKeys.jl)
 
+<!--<img src="docs/readmefigure.png" alt="block picture" width="400" align="right">-->
+
 This package defines a thin wrapper which, alongside any array, stores a vector of "keys" 
 for each dimension. This may be useful to store perhaps actual times of measurements, 
 or some strings labeling columns, etc. These will be propagated through many 
 operations on arrays, including broadcasting, `map`, comprehensions, `sum` etc.
 
-It works closely with [NamedDims.jl](https://github.com/invenia/NamedDims.jl), 
+It works closely with [NamedDims.jl](https://github.com/invenia/NamedDims.jl), another wrapper 
 which attaches names to dimensions. These names are a tuple of symbols, like those of 
 a `NamedTuple`. They can be used for specifying which dimensions to sum over, etc.
-
-The function `wrapdims` constructs a nested pair of these wrappers,
-for example: 
+The function `wrapdims` constructs a nested pair of these wrappers, for example: 
 
 ```julia
 using AxisKeys
 data = rand(Int8, 2,10,3) .|> abs;
-A = wrapdims(data; channel=[:left, :right], time=range(13, step=2.5, length=10), iter=31:33)
+A = KeyedArray(data; channel=[:left, :right], time=range(13, step=2.5, length=10), iter=31:33)
 ```
 
-<center>
-<img src="docs/readmeterminal.png" alt="??" width="600" align="center"></img>
-</center>
+<p align="center">
+<img src="docs/readmeterminal.png" alt="terminal pretty printing" width="550" align="center">
+</p>
 
 ### Selections
 
@@ -48,14 +48,14 @@ There are also a numer of special selectors, which work like this:
 |-----------------|------------------|-------------------------|---------|
 | one nearest     | `B[time = 3]`    | `B(time = Near(17.0))`  | vector  |
 | all in a range  | `B[2:5, :]`      | `B(Interval(14,25), :)` | matrix  |
-| all matching    | `B[3:end, 3:3]`  | `B(>(17), ==(33))`      | matrix  |
+| all matching    | `B[3:end, Not(3)]` | `B(>(17), !=(33))`      | matrix  |
 | mixture         | `A[1, 2, end]`   | `A(:left, Index[2], Index[end])` | scalar |
 | non-scalar      | `B[iter=[1, 3]]` | `B(iter=[31, 33])`      | matrix  |
 
 Here `Interval(13,18)` can also be written `13..18`, it's from [IntervalSets.jl](https://github.com/JuliaMath/IntervalSets.jl). 
 Any functions can be used to select keys, including lambdas: `B(time = t -> 0<t<17)`. 
 You may give just one `::Base.Fix2` function 
-(such as `<=(18)` or `!=(20)`) provided its argument type matches the keys of one dimension.
+(such as `<=(18)` or `==(20)`) provided its argument type matches the keys of one dimension.
 An interval or a function always selects via `findall`, 
 i.e. it does not drop a dimension, even if there is exactly one match. 
 
@@ -67,24 +67,27 @@ as a trailing colon makes a zero-dimensional view.
 
 (Possibly selectors should be made to work in square brackets too,
 allowing mixed indexing `B[1, Key('β')] == B(Index[1], 'β')` 
-and `setkey!` via `B[Key(13.0), Key('α')] = 0`. But they don't right now.)
+and `setkey!` via `B[Key(13.0), Key('α')] = 0`. But they don't right now,
+see [PR#5](https://github.com/mcabbott/AxisKeys.jl/pull/5) for an attempt.)
 
 ### Construction
 
 ```julia
-KeyedArray(rand(Int8, 2,10), ([:a, :b], 10:10:100))
+KeyedArray(rand(Int8, 2,10), ([:a, :b], 10:10:100)) # AbstractArray, Tuple{AbstractVector, ...}
 ```
 
-A nested pair with names can be constructed with keywords, 
-and (apart from a few bugs) this should work the same in either order:
+A nested pair with names can be constructed with keywords for names,
+and (apart from a few bugs) everything should work the same way in either order:
 
 ```julia
 KeyedArray(rand(Int8, 2,10), row=[:a, :b], col=10:10:100)     # KeyedArray(NamedDimsArray(...))
 NamedDimsArray(rand(Int8, 2,10), row=[:a, :b], col=10:10:100) # NamedDimsArray(KeyedArray(...))
 ```
 
-The function `wrapdims` does a bit more checking and fixing. 
-It will adjust the length of key vectors if it can, and their indexing if needed to match the array:
+The function `wrapdims` does a bit more checking and fixing, but is not type-stable. 
+It will adjust the length of ranges of keys if it can, 
+and will fix indexing offsets if needed to match the array. 
+The resulting order of wrappers is controlled by `AxisKeys.nameouter()=false`.
 
 ```julia
 wrapdims(rand(Int8, 10), alpha='a':'z') 
@@ -98,35 +101,41 @@ axiskeys(ans,1) # 10:10:100 with indices 0:9
 
 As usual `axes(A)` returns (a tuple of vectors of) indices, 
 and `axiskeys(A)` returns (a tuple of vectors of) keys.
-If the array has names, then `dimnames(A)` returns them, 
-and functions like `axes(A, name)` give just one.
+If the array has names, then `dimnames(A)` returns them.
+These functions work like `size(A, d) = size(A, name)` to get just one.
 
 Many functions should work, for example:
 
-* Reductions like `sum(A; dims=:channel)` can use dimension names. 
-  Likewise `prod`, `mean` etc., and `dropdims`.
-
 * Broadcasting `log.(A)` and `map(log, A)`, as well as comprehensions 
   `[log(x) for x in A]` should all work. 
 
-* Transpose etc, `permutedims`.  
+* Transpose etc, `permutedims`, `mapslices`.
 
 * Concatenation `hcat(B, B .+ 100)` works. 
   Note that the keys along the glued direction may not be unique afterwards.
 
+* Reductions like `sum(A; dims=:channel)` can use dimension names. 
+  Likewise `prod`, `mean` etc., and `dropdims`.
+
 * Some linear algebra functions like `*` and `\` will work. 
 
 * Getproperty returns the key vector, to allow things like
-  `for (i,t) in enumerate(A.time); fun(A[i], t); ...`.
+  `for (i,t) in enumerate(A.time); fun(val = A[i,:], time = t); ...`.
 
 * Vectors support `push!(V, val)`, which will try to extend the key vector. 
   There is also a method `push!(V, key => val)` which pushes in a new key. 
 
 To allow for this limited mutability, `V.keys isa Ref` for vectors, 
 while `A.keys isa Tuple` for matrices & higher. But `axiskeys(A)` always returns a tuple.
 
-* [LazyStack](https://github.com/mcabbott/LazyStack.jl)`.stack` is now hooked up.
-  Stacks of named tuples like `stack((a=i, b=i^2) for i=1:3)` create axis keys.
+* Named tuples can be converted to and from keyed vectors,
+  with `collect(keys(nt)) == Symbol.(axiskeys(V),1)`
+
+* [LazyStack](https://github.com/mcabbott/LazyStack.jl)`.stack` understands names and keys.
+  Stacks of named tuples like `stack((a=i, b=i^2) for i=1:5)` create a matrix with `[:a, :b]`.
+
+* [NamedPlus](https://github.com/mcabbott/NamedPlus.jl) has a macro which works on comprehensions:
+  `@named [n^pow for n=1:10, pow=0:2:4]` has names and keys.
 
 ### Absent
 
@@ -234,4 +243,4 @@ In 🐍-land:
   [DataFrames](https://github.com/JuliaData/DataFrames.jl), only one- and two-dimensional.
   Writes indexing "by position" as `df.iat[1, 1]` for scalars or `df.iloc[1:3, :]` allowing slices,
   and lookup "by label" as `df.at[dates[0], 'A']` for scalars or `df.loc['20130102':'20130104', ['A', 'B']]` for slices, "both endpoints are *included*" in this.
-
+  See also [Pandas.jl](https://github.com/JuliaPy/Pandas.jl) for a wrapper.

docs/readmefigure.png

@@ -31,14 +31,14 @@ Text["[:l, :r]",{10.5,1.5,4},{-1,-1},{4,-1}]
 },
 {Darker[Orange],
 Arrow[Tube[{{10.5,0.1,0.8}, {10.5,0.1,3.5}}]],
-Text["'\[Alpha]':'\[Gamma]'",{10.5,0,2},{0,1},{1,20}]
+Text["31:33",{10.5,0,2},{0,1},{1,20}]
 }
 
 },
 Boxed->False, 
 Axes->True,
 Ticks->{Range[10], Range[2], Range[3]},
-AxesLabel->{":time", ":channel", ":z"},
+AxesLabel->{":time", ":channel", ":iter"},
 AxesStyle->Directive[Darker[Gray], Thickness[0.004]],
 
 (*FormatType\[Rule]StandardForm,*)

docs/readmefigure.wl

@@ -1,11 +1,19 @@
-julia> #===== Examples of how to use the AxisArrays package. =====#
+julia> #===== Examples of how to use the AxisKeys package. =====#
 
-(v1.3) pkg> add https://github.com/mcabbott/AxisKeys.jl # Not a registered package
+(v1.3) pkg> add AxisKeys  # Now registered
 
 julia> using AxisKeys, Random
 
 julia> Random.seed!(42);
 
+julia> KeyedArray((a=3, b=5, c=7)) # Using keys of a NamedTuple
+1-dimensional KeyedArray(...) with keys:
+↓   3-element Vector{Symbol}
+And data, 3-element Array{Int64,1}:
+ (:a)  3
+ (:b)  5
+ (:c)  7
+
 julia> D = wrapdims(rand(Int8,5), iter = 10:10:50) # Convenience constructor
 1-dimensional KeyedArray(NamedDimsArray(...)) with range:
 ↓   iter ∈ 5-element StepRange{Int64,...}
@@ -39,7 +47,7 @@ julia> @view E[col=1] # Fixing one index gives a slice
 ↓ row  -105
           3
 
-julia> C = wrapdims(rand(2,10) .+ (0:1), obs=["dog", "cat"], time=range(0, step=0.5, length=10))
+julia> C = KeyedArray(rand(2,10) .+ (0:1), obs=["dog", "cat"], time=range(0, step=0.5, length=10))
 2-dimensional KeyedArray(NamedDimsArray(...)) with ranges:
 ↓   obs ∈ 2-element Vector{String}
 →   time ∈ 10-element StepRangeLen{Float64,...}
@@ -48,7 +56,7 @@ And data, 2×10 Array{Float64,2}:
   ("dog")    0.160006    0.602298    0.383491    0.745181       0.0823367    0.452418    0.281987
   ("cat")    1.42296     1.36346     1.59291     1.26281        1.24468      1.76372     1.14364
 
-julia> names(C) # Works like size & axes, i.e. names(C,2) == :time
+julia> dimnames(C) # Works like size & axes, i.e. dimnames(C,2) == :time
 (:obs, :time)
 
 julia> axiskeys(C) # Likewise, axiskeys(C, :time) == 0:0.5:4.5
@@ -89,10 +97,10 @@ And data, 2×2 Array{Float64,2}:
   ("cat")   5.85958  21.8234
 
 julia> ans("mouse")
-ERROR: key of type String is ambiguous, matches dimensions (1, 2)
+ERROR: ArgumentError: key of type String is ambiguous, matches dimensions (1, 2)
 
 julia> C("mouse")
-ERROR: could not find key "mouse" in range ["dog", "cat"]
+ERROR: ArgumentError: could not find key "mouse" in vector ["dog", "cat"]
 
 julia> for (i,t) in enumerate(C.time)
        t > 3 && println("at time $t, value cat = ", C[2,i])
@@ -178,7 +186,19 @@ And data, 3×81×2 Array{Float64,3}:
   (:b)      0.123933      0.988803     0.243089         0.701553       0.11737
   (:c)      0.850917      0.0495313    0.0470764        0.322251       0.642556
 
-# Ranges are printed with colours based on eltype, btw!
-
-julia> H(:a, -14, "one") # uses UniqueVector's fast lookup
+julia> H(:a, -14, "one") # uses the UniqueVector's fast lookup
 0.9948971186701887
+
+julia> using LazyStack # A package for concatenating arrays
+
+julia> stack(:pre, n .* D for n in 1:10)
+2-dimensional NamedDimsArray(KeyedArray(...)) with keys:
+↓   iter ∈ 5-element StepRange{Int64,...}
+→   pre ∈ 10-element OneTo{Int}
+And data, 5×10 Array{Int64,2}:
+       (1)  (2)  (3)  (4)  (5)  (6)  (7)  (8)   (9)  (10)
+ (10)  115  230  345  460  575  690  805  920  1035  1150
+ (20)   99  198  297  396  495  594  693  792   891   990
+ (30)    0    0    0    0    0    0    0    0     0     0
+ (40)   57  114  171  228  285  342  399  456   513   570
+ (50)   88  176  264  352  440  528  616  704   792   880

docs/readmeterminal.png

@@ -4,7 +4,7 @@ and of other packages of similar or overlapping concerns.
 Plus generally a place to collect their various syntax, for comparison.
 =#
 
-using AxisKeys, BenchmarkTools # Julia 1.3 + macbook escape
+using AxisKeys, BenchmarkTools # Julia 1.4 + macbook escape
 
 #==============================#
 #===== getkey vs getindex =====#
@@ -19,9 +19,9 @@ bothmat2 = wrapdims(mat.data, x=collect(11:13), y=collect(21:24))
 
 @btime $bothmat[3,4]        # 1.700 ns
 @btime $bothmat[x=3, y=4]   # 1.701 ns
-@btime $bothmat(13, 24)     # 5.874 ns
-@btime $bothmat(x=13, y=24) # 43.302 ns (2 allocations: 64 bytes)
-@btime $bothmat2(13, 24)    # 16.719 ns
+@btime $bothmat(13, 24)     # 5.874 ns -- fast range lookup
+@btime $bothmat(x=13, y=24) # 14.063 ns
+@btime $bothmat2(13, 24)    # 16.719 ns -- collected vector
 
 ind_collect(A) = [@inbounds(A[ijk...]) for ijk in Iterators.ProductIterator(axes(A))]
 key_collect(A) = [@inbounds(A(vals...)) for vals in Iterators.ProductIterator(axiskeys(A))]
@@ -31,14 +31,14 @@ bigmat2 = wrapdims(rand(100,100), collect(1:100), collect(1:100));
 
 @btime ind_collect($(bigmat.data)); #  9.117 μs (4 allocations: 78.25 KiB)
 @btime ind_collect($bigmat);        # 11.530 μs (4 allocations: 78.25 KiB)
-@btime key_collect($bigmat);        # 20.671 μs (4 allocations: 78.27 KiB) -- fast range lookup
+@btime key_collect($bigmat);        # 64.064 μs (4 allocations: 78.27 KiB) -- fast range lookup, was 20μs!
 @btime key_collect($bigmat2);      # 718.804 μs (5 allocations: 78.27 KiB) -- findfirst(..., vector) lookup
 
 twomat = wrapdims(mat.data, x=[:a, :b, :c], y=21:24)
-@btime $twomat(x=:a, y=24)  # 57.396 ns (2 allocations: 64 bytes)
+@btime $twomat(x=:a, y=24)  # 36.734 ns (2 allocations: 64 bytes)
 
 @btime $twomat(24.0)        # 26.686 ns (4 allocations: 112 bytes)
-@btime $twomat(y=24.0)      # 52.372 ns (6 allocations: 144 bytes)
+@btime $twomat(y=24.0)      # 33.860 ns (4 allocations: 112 bytes)
 @btime view($twomat, :,3)   # 24.951 ns (4 allocations: 112 bytes)
 
 
@@ -50,7 +50,7 @@ using OffsetArrays                      #===== OffsetArrays =====#
 
 of1 = OffsetArray(rand(3,4), 11:13, 21:24)
 
-@btime $of1[13,24] # 3.652 ns
+@btime $of1[13,24] # 1.700 ns
 
 bigoff = OffsetArray(bigmat.data, 1:100, 1:100);
 @btime ind_collect($bigoff);        # 15.372 μs (5 allocations: 78.30 KiB)

docs/repl.jl

@@ -5,14 +5,16 @@ export KeyedArray, axiskeys
 
 include("axes.jl")
 
+include("lookup.jl")
+
 include("names.jl")
 export NamedDimsArray, dimnames
 
 include("wrap.jl")
 export wrapdims
 
 include("selectors.jl")
-export Near, Index, Interval
+export Near, Index, Interval, Not
 
 include("functions.jl")