Merge c0f8047 into d3081c7

docs/src/apply.md

@@ -60,6 +60,22 @@ put the last observation in the object (which happens to be on Dec 31,
 lead(cl, 499)
 ```
 
+## `diff`
+
+Differentiating a time series calculates the finite difference between
+two consecutive points in the time series. The resulting time series
+will have less points than the original. Those points are filled with
+`NaN` values if `padding=true`.
+
+```@repl diff
+diff(cl)
+```
+
+You can calculate higher order differences by using the keyword
+parameter `differences`, accepting a positive integer. The default
+value is `differences=1`. For instance, passing `differences=2` is
+equivalent to doing `diff(diff(cl))`.
+
 ## `percentchange`
 
 Calculating change between timestamps is a very common time series

src/apply.jl

@@ -48,10 +48,11 @@ end  # lead
 
 ###### diff #####################
 
-# TODO: Support higher-order differencing?
-function diff(ta::TimeArray; padding::Bool=false)
+function diff(ta::TimeArray; padding::Bool=false, differences::Int=1)
     cols = ta.colnames
-    ta = ta .- lag(ta, padding=padding)
+    for d in 1:differences
+        ta = ta .- lag(ta, padding=padding)
+    end
     ta.colnames[:] = cols
     return ta
 end  # diff

test/apply.jl

@@ -62,6 +62,22 @@ using TimeSeries
         @test diff(op, padding=true).values[2]                == op[2].values[1] .- op[1].values[1]
     end
 
+    @testset "diff calculates 2nd-order differences" begin
+        @test diff(op, differences=2).timestamp               == diff(op, padding=false, differences=2).timestamp
+        @test diff(op, differences=2).values                  == diff(op, padding=false, differences=2).values
+        @test diff(diff(op)).timestamp                        == diff(op, padding=false, differences=2).timestamp
+        @test diff(diff(op)).values                           == diff(op, padding=false, differences=2).values
+        @test diff(op, padding=true, differences=2).values[3] == diff(op, differences=2).values[1]
+    end
+
+    @testset "diff calculates 3rd-order differences" begin
+        @test diff(op, differences=3).timestamp               == diff(op, padding=false, differences=3).timestamp
+        @test diff(op, differences=3).values                  == diff(op, padding=false, differences=3).values
+        @test diff(diff(diff(op))).timestamp                  == diff(op, padding=false, differences=3).timestamp
+        @test diff(diff(diff(op))).values                     == diff(op, padding=false, differences=3).values
+        @test diff(op, padding=true, differences=3).values[4] == diff(op, differences=3).values[1]
+    end
+
     @testset "simple return value" begin
         @test percentchange(cl, :simple).values == percentchange(cl).values
         @test percentchange(cl).values          == percentchange(cl, padding=false).values