Public API Reference

TimeArray{T,N,D<:TimeType,A<:AbstractArray{T,N}} <: AbstractTimeSeries{T,N,D}

Constructors

TimeArray(timestamp, values[, colnames, meta = nothing])
TimeArray(ta::TimeArray; timestamp, values, colnames, meta)
TimeArray(data::NamedTuple; timestamp, meta = nothing)
TimeArray(table; timestamp::Symbol, timeparser::Callable = identity)

The second constructor yields a new TimeArray with the new given fields. Note that the unchanged fields will be shared, there aren't any copy for the underlying arrays.

The third constructor builds a TimeArray from a NamedTuple.

Arguments

• timestamp::AbstractVector{<:TimeType}: a vector of sorted timestamps,

• timestamp::Symbol: the column name of the time index from the source table. The constructor is used for the Tables.jl package integration.

• values::AbstractArray: a data vector or matrix. Its number of rows should match the length of timestamp.

• colnames::Vector{Symbol}: the column names. Its length should match the column of values.

• meta::Any: a user-defined metadata.

• timeparser::Callable: a mapping function for converting the source time index. For instance, Dates.unix2datetime is a common case.

Examples

data = (datetime = [DateTime(2018, 11, 21, 12, 0), DateTime(2018, 11, 21, 13, 0)],
        col1 = [10.2, 11.2],
        col2 = [20.2, 21.2],
        col3 = [30.2, 31.2])
ta = TimeArray(data; timestamp = :datetime, meta = "Example")

diff(ta::TimeArray, n::Int=1; padding::Bool=false, differences::Int=1)

Difference a TimeArray by n periods, optionally multiple times (differences).

merge(ta1::TimeArray{T}, ta2::TimeArray{T}, [tas::TimeArray{T}...];
      method = :inner, colnames = [...], padvalue = NaN)

Merge several TimeArrays along with the time index.

Argument

• method::Symbol: :inner, :outer, :left or :right.

values(ta::TimeArray)

Get the underlying value table of a TimeArray.

basecall(ta::TimeArray, f::Function; cnames=colnames(ta))

Apply function f to the values of a TimeArray and return a new TimeArray.

collapse(ta, period, timestamp; ...)
collapse(ta, period, timestamp, value; kw...)

The collapse method allows for compressing data into a larger time frame.

For example, converting daily data into monthly data. When compressing dates, something rational has to be done with the values that lived in the more granular time frame. To define what happens, a function call is made.

Arguments:

• ta::TimeArray: Original data
• period::Union{Function,Dates.Period}: Period or method for determining the period
• timestamp::Function: Method that determines which timestamp represents the whole period, e.g. last
• value::Function = timestamp: Method that should be applied to the data within the period, e.g. mean

collapse(ta, month, last)
collapse(ta, month, last, mean)

colnames(ta::TimeArray)

Get the column names of a TimeArray.

Examples

julia> colnames(ohlc)
4-element Array{Symbol,1}:
 :Open
 :High
 :Low
 :Close

dropnan(ta::TimeArray, method::Symbol=:all)

Drop rows from a TimeArray where values are NaN. Use :all or :any for method.

findwhen(ta::TimeArray{Bool,1})

Return timestamps where the values of a boolean TimeArray are true.

from(ta::TimeArray{T,N,D}, d::D)

Return the part of TimeArray from the first timestamp >= d.

head(ta::TimeArray{T,N}, n::Int=6)

Return the first n rows of a TimeArray.

lag(ta::TimeArray{T,N}, n::Int=1; padding::Bool=false, period::Int=0)

Lag a TimeArray by n periods. Optionally pad with NaN or use the deprecated period keyword.

lead(ta::TimeArray{T,N}, n::Int=1; padding::Bool=false, period::Int=0)

Lead a TimeArray by n periods. Optionally pad with NaN or use the deprecated period keyword.

meta(ta::TimeArray)

Get the user-defined metadata of a TimeArray.

moving(f, ta::TimeArray{T,1}, w::Integer; padding = false)

Apply user-defined function f to a 1D TimeArray with window size w.

Example

To calculate the simple moving average of a time series:

moving(mean, ta, 10)

moving(f, ta::TimeArray{T,2}, w::Integer; padding = false, dims = 1, colnames = [...])

Example

In case of dims = 2, the user-defined function f will get a 2D Array as input.

moving(ohlc, 10; dims=2, colnames=[:A, ...]) do
    # given that `ohlc` is a 500x4 `TimeArray`,
    # size(A) is (10, 4)
    ...
end

percentchange(ta::TimeArray, returns::Symbol=:simple; padding::Bool=false, method::AbstractString="")

Compute percent change of a TimeArray. Use :simple or :log returns.

Arguments

• padding::Bool=false: If true, pads the beginning of the result with NaN values so the output has the same length as the input. If false, the result is shorter by one (or more, depending on differencing).

Example

using TimeSeries, Dates
ta = TimeArray(Date(2020,1,1):Day(1):Date(2020,1,3), [1,2,4], ["A"])
percentchange(ta, :simple; padding=true)
# Output:
# 3×1 TimeArray{Float64,1,Date,Array{Float64,2}}
# │            │ A      │
# ├────────────┼────────┤
# │ 2020-01-01 │   NaN  │
# │ 2020-01-02 │   1.0  │
# │ 2020-01-03 │   1.0  │

readtimearray(source; delim=',', meta=nothing, format="", header=true)

Read a CSV or delimited file into a TimeArray.

rename!(ta::TimeArray, colnames::Vector{Symbol})
rename!(ta::TimeArray, colname::Symbol)
rename!(ta::TimeArray, orig => new, ...)
rename!(f::Base.Callable, ta, colnametyp)

In-place rename the columns of a TimeArray.

See also rename.

Arguments

• colnametyp is the input type for the function f. The valid value is Symbol or String.

rename(ta::TimeArray, colnames::Vector{Symbol})
rename(ta::TimeArray, colname::Symbol)
rename(ta::TimeArray, orig => new, ...)
rename(f::Base.Callable, ta, colnametyp)

Rename the columns of a TimeArray.

See also rename!.

Arguments

• colnametyp is the input type for the function f. The valid value is Symbol or String.

tail(ta::TimeArray{T,N}, n::Int=6)

Return the last n rows of a TimeArray.

timestamp(ta::TimeArray)

Get the time index of a TimeArray.

to(ta::TimeArray{T,N,D}, d::D)

Return the part of TimeArray up to the last timestamp <= d.

uniformspace(ta::TimeArray{T,N})

Return a new TimeArray with a uniform time grid, filling missing values with NaN.

uniformspaced(ta::TimeArray)

Check if the timestamps of a TimeArray are uniformly spaced.

upto(f, ta::TimeArray{T,1})

Apply function f cumulatively up to each index of a 1D TimeArray.

upto(f, ta::TimeArray{T,2})

Apply function f cumulatively up to each index of a 2D TimeArray (column-wise).

when(ta::TimeArray, period::Function, t::Integer)

Return a subset of TimeArray where the period function applied to timestamps equals t.

writetimearray(ta::TimeArray, fname::AbstractString; delim=',', format="", header=true)

Write a TimeArray to a CSV or delimited file.

hcat(x::TimeArray, y::TimeArray)

Horizontally concatenate two TimeArray objects with matching timestamps and columns.

hcat(x::TimeArray, y::TimeArray, zs::Vararg{TimeArray})

Horizontally concatenate multiple TimeArray objects.

vcat(tas)

Concatenate two $TimeArray$ into single object.

If there are duplicated timestamps, we will keep order as the function input.

julia> a = TimeArray([Date(2015, 10, 1), Date(2015, 10, 2), Date(2015, 10, 3)], [1, 2, 3]);

julia> b = TimeArray([Date(2015, 10, 2), Date(2015, 10, 3)], [4, 5]);

julia> [a; b]
5×1 TimeArray{Int64,1,Date,Array{Int64,1}} 2015-10-01 to 2015-10-03
│            │ A     │
├────────────┼───────┤
│ 2015-10-01 │ 1     │
│ 2015-10-02 │ 2     │
│ 2015-10-02 │ 4     │
│ 2015-10-03 │ 3     │
│ 2015-10-03 │ 5     │

map(f, ta::TimeArray{T,N})

Apply function f to each row of a TimeArray, returning a new TimeArray.

Example

using TimeSeries, Dates
ta = TimeArray(Date(2020,1,1):Day(1):Date(2020,1,3), [1,2,3], ["A"])
# Add 10 to each value, keep timestamp
map((t, v) -> (t, v .+ 10), ta)
# Output:
# 3×1 TimeArray{Int64,1,Date,Array{Int64,2}}  
# │            │ A   │
# ├────────────┼─────┤
# │ 2020-01-01 │ 11  │
# │ 2020-01-02 │ 12  │
# │ 2020-01-03 │ 13  │

split(data::TimeSeries.TimeArray, period::Function)

Split data by period function, returns a vector of TimeSeries.TimeArray.

Arguments

• data::TimeSeries.TimeArray: Data to split
• period::Function: Function, e.g. Dates.day that is used to split the data.

+(ta::TimeArray)

Element-wise unary plus for a TimeArray.

-(ta::TimeArray)

Element-wise unary minus for a TimeArray.

==(x::TimeArray, y::TimeArray)

If true, all fields of x and y should be equal, meaning that the two TimeArrays have the same values at the same points in time, the same colnames and the same metadata.

Implies

x.timestamp == y.timestamp &&
    x.values == y.values &&
    x.colnames == y.colnames &&
    x.meta == y.meta

eachrow(x::TimeArray)

Return a row iterator baked by Tables.rows.

Examples

for row in eachrow(ohlc)
    time = row.timestamp
    price = row.Close
end

eachcol(x::TimeArray)

Return a column iterator baked by Tables.columns.