Add sort transform (#87)

* add sort transform

* rename ascending parameter to rev

* fix column table access

* remove duplicated break line

Co-authored-by: Júlio Hoffimann <[email protected]>

* rename by parameter to col

* Update src/transforms/sort.jl

* Update src/transforms/sort.jl

* add sort transform to doc page

* Update src/transforms/sort.jl

Co-authored-by: Elias Carvalho <[email protected]>

* Add support for all sort function kwargs

* Add colspec

* Add tests

* Update docstring

* Remove notes

Co-authored-by: Claro Henrique <[email protected]>
Co-authored-by: Júlio Hoffimann <[email protected]>
Co-authored-by: Elias Carvalho <[email protected]>

Author: 4 people

docs/src/transforms/builtin.md

@@ -121,6 +121,12 @@ Functional
 Levels
 ```
 
+## Sort
+
+```@docs
+Sort
+```
+
 ## EigenAnalysis
 
 ```@docs

src/TableTransforms.jl

@@ -47,6 +47,7 @@ export
   Quantile,
   Functional,
   Levels,
+  Sort,
   EigenAnalysis,
   PCA, DRS, SDS,
   Sequential,

src/transforms.jl

@@ -227,6 +227,7 @@ include("transforms/zscore.jl")
 include("transforms/quantile.jl")
 include("transforms/functional.jl")
 include("transforms/levels.jl")
+include("transforms/sort.jl")
 include("transforms/eigenanalysis.jl")
 include("transforms/sequential.jl")
-include("transforms/parallel.jl")
+include("transforms/parallel.jl")

src/transforms/sort.jl

@@ -0,0 +1,70 @@
+# ------------------------------------------------------------------
+# Licensed under the MIT License. See LICENSE in the project root.
+# ------------------------------------------------------------------
+
+"""
+    Sort(col₁, col₂, ..., colₙ; kwargs...)
+    Sort([col₁, col₂, ..., colₙ]; kwargs...)
+    Sort((col₁, col₂, ..., colₙ); kwargs...)
+
+Sort the rows of selected columns `col₁`, `col₂`, ..., `colₙ` by forwarding
+the `kwargs` to the `sortperm` function.
+
+    Sort(regex; kwargs...)
+
+Sort the rows of columns that match with `regex`.
+
+# Examples
+
+```julia
+Sort(:a)
+Sort(:a, :c, rev=true)
+Sort([1, 3, 5], by=row -> abs.(row))
+Sort(("a", "c", "e"))
+Sort(r"[ace]")
+```
+"""
+struct Sort{S<:ColSpec,T} <: Stateless
+  colspec::S
+  kwargs::T
+end
+
+Sort(colspec::S; kwargs...) where {S<:ColSpec} = 
+  Sort(colspec, values(kwargs))
+
+Sort(cols::T...; kwargs...) where {T<:ColSelector} = 
+  Sort(cols, values(kwargs))
+
+# argument errors
+Sort(::Tuple{}; kwargs...) = throw(ArgumentError("Cannot create a Sort object with empty tuple."))
+Sort(; kwargs...) = throw(ArgumentError("Cannot create a Sort object without arguments."))
+
+isrevertible(::Type{<:Sort}) = true
+
+function apply(transform::Sort, table)
+  cols = Tables.columns(table)
+  names = Tables.columnnames(cols)
+  snames = choose(transform.colspec, names)
+  
+  # use selected columns to calculate new order
+  scols = collect(zip(Tables.getcolumn.(Ref(cols), snames)...))
+  inds = sortperm(scols; transform.kwargs...)
+
+  # sort rows
+  rows = Tables.rowtable(table)
+  rows = rows[inds]
+
+  newtable = rows |> Tables.materializer(table)
+  newtable, inds
+end
+
+function revert(::Sort, newtable, cache)
+  # use cache to recalculate old order
+  inds = sortperm(cache)
+
+  # undo rows sort
+  rows = Tables.rowtable(newtable)
+  rows = rows[inds]
+
+  rows |> Tables.materializer(newtable)
+end

test/transforms.jl

@@ -1333,6 +1333,98 @@
     @test isordered(tₒ.b) == false
   end
 
+  @testset "Sort" begin
+    a = [5, 3, 1, 2]
+    b = [2, 4, 8, 5]
+    c = [3, 2, 1, 4]
+    d = [4, 3, 7, 5]
+    t = Table(; a, b, c, d)
+
+    T = Sort(:a)
+    n, c = apply(T, t)
+    @test Tables.schema(t) == Tables.schema(n)
+    @test n.a == [1, 2, 3, 5]
+    @test n.b == [8, 5, 4, 2]
+    @test n.c == [1, 4, 2, 3]
+    @test n.d == [7, 5, 3, 4]
+    @test isrevertible(T) == true
+    tₒ = revert(T, n, c)
+    @test t == tₒ
+
+    # descending order test
+    T = Sort(:b, rev=true)
+    n, c = apply(T, t)
+    @test Tables.schema(t) == Tables.schema(n)
+    @test n.a == [1, 2, 3, 5]
+    @test n.b == [8, 5, 4, 2]
+    @test n.c == [1, 4, 2, 3]
+    @test n.d == [7, 5, 3, 4]
+    tₒ = revert(T, n, c)
+    @test t == tₒ
+
+    # random test
+    a = rand(200)
+    b = rand(200)
+    c = rand(200)
+    d = rand(200)
+    t = Table(; a, b, c, d)
+
+    T = Sort(:c)
+    n, c = apply(T, t)
+
+    @test Tables.schema(t) == Tables.schema(n)
+    @test issetequal(Tables.rowtable(t), Tables.rowtable(n))
+    @test issorted(Tables.getcolumn(n, :c))
+    tₒ = revert(T, n, c)
+    @test t == tₒ
+
+    # sort by multiple columns
+    a = [-2, -1, -2, 2, 1, -1, 1, 2]
+    b = [-8, -4, 6, 9, 8, 2, 2, -8]
+    c = [-3, 6, 5, 4, -8, -7, -1, -10]
+    t = Table(; a, b, c)
+
+    T = Sort(1, 2)
+    n, c = apply(T, t)
+    @test n.a == [-2, -2, -1, -1, 1, 1, 2, 2]
+    @test n.b == [-8, 6, -4, 2, 2, 8, -8, 9]
+    @test n.c == [-3, 5, 6, -7, -1, -8, -10, 4]
+    tₒ = revert(T, n, c)
+    @test t == tₒ
+
+    T = Sort([:a, :c], rev=true)
+    n, c = apply(T, t)
+    @test n.a == [2, 2, 1, 1, -1, -1, -2, -2]
+    @test n.b == [9, -8, 2, 8, -4, 2, 6, -8]
+    @test n.c == [4, -10, -1, -8, 6, -7, 5, -3]
+    tₒ = revert(T, n, c)
+    @test t == tₒ
+
+    T = Sort(("b", "c"), by=row -> abs.(row))
+    n, c = apply(T, t)
+    @test n.a == [1, -1, -1, -2, -2, 1, 2, 2]
+    @test n.b == [2, 2, -4, 6, -8, 8, -8, 9]
+    @test n.c == [-1, -7, 6, 5, -3, -8, -10, 4]
+    tₒ = revert(T, n, c)
+    @test t == tₒ
+
+    # throws: Sort without arguments
+    @test_throws ArgumentError Sort()
+    @test_throws ArgumentError Sort(())
+
+    # throws: empty selection
+    @test_throws AssertionError apply(Sort(r"x"), t)
+    @test_throws AssertionError apply(Sort(Symbol[]), t)
+    @test_throws AssertionError apply(Sort(String[]), t)
+
+    # throws: columns that do not exist in the original table
+    @test_throws AssertionError apply(Sort([:d, :e]), t)
+    @test_throws AssertionError apply(Sort(("d", "e")), t)
+
+    # Invalid kwarg
+    @test_throws MethodError apply(Sort(:a, :b, test=1), t)
+  end
+
   @testset "EigenAnalysis" begin
     # PCA test
     x = rand(Normal(0, 10), 1500)