GitHub

The TimeArray time series type

The TimeArray time series type is defined here (with inner constructor code removed for readability):

struct TimeArray{T,N,D<:TimeType,A<:AbstractArray{T,N}} <: AbstractTimeSeries{T,N,D}
    timestamp::Vector{D}
    values::A # some kind of AbstractArray{T,N}
    colnames::Vector{Symbol}
    meta::Any

    # inner constructor code enforcing invariants
end

There are four fields for the type.

timestamp

The timestamp field consists of a vector of values of a child type of of TimeType - in practise either Date or DateTime. The DateTime type is similar to the Date type except it represents time frames smaller than a day. For the construction of a TimeArray to work, this vector needs to be sorted. If the vector includes dates that are not sequential, the construction of the object will error out. The vector also needs to be ordered from oldest to latest date, but this can be handled by the constructor and will not prohibit an object from being created.

values

The values field holds the data from the time series and its row count must match the length of the timestamp array. If these do not match, the constructor will fail. All the values inside the values array must be of the same type.

colnames

The colnames field is a vector of Symbol and contains the names of the columns for each column in the values field. The length of this vector must match the column count of the values array, or the constructor will fail. Since TimeArrays are indexable on column names, duplicate names in the colnames vector will be modified by the inner constructor. Each subsequent duplicate name will be appended by _n where n enumerates from 1.

meta

The meta field defaults to holding nothing, which is represented by type Nothing. This default is designed to allow programmers to ignore this field. For those who wish to utilize this field, meta can hold common types such as String or more elaborate user-defined types. One might want to assign a name to an object that is immutable versus relying on variable bindings outside of the object's type fields.

Constructors

TimeSeries.TimeArray — Type
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")
source

Fields getter functions

There are four field getter functions exported. They are named as same as the field names.

Base.values — Function
values(ta::TimeArray)

Get the underlying value table of a TimeArray.

source
TimeSeries.colnames — Function
colnames(ta::TimeArray)

Get the column names of a TimeArray.

Examples

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