TimeSeriesEcon Reference

TimeSeriesEcon

This package is part of the StateSpaceEcon ecosystem. Provides the data types and functionality necessary to work with macroeconomic discrete time models.

Working with time

• Frequencies are represented by abstract type Frequency.
• Concrete frequencies include Yearly, Quarterly and Monthly.
• Moments in time are represented by data type MIT.
• Lengths of time are represented by data type Duration.

Working with time series

• Data type TSeries represents a single time series.
• Data type MVTSeries represents a multivariate time series.

Working with other data

• Data type Workspace is a general purpose dictionary-like collection of "variable"-like objects.

Tutorial

• TimeSeriesEcon tutorial

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

struct BDaily <: CalendarFrequency end

Represents a business daily frequency (excludes weekends).

See also: Frequency

abstract type CalendarFrequency <: Frequencies  end

Represents frequencies associated with a specific gregorian calendar position.

See also: Frequency, YPFrequency

struct Daily <: CalendarFrequency end

Represents a daily frequency.

See also: CalendarFrequency

MIT{F <: Frequency}, Duration{F <: Frequency}

Two types representing a moment in time (like 2020Q1 or 2020Y) and duration (the quantity of time between two moments).

Both of these have a Frequency as a type parameter and both internally are represented by integer values.

If you imagine a time axis of the given Frequency, MIT values are ordinal (correspond to points) while Duration values are cardinal (correspond to distances).

abstract type Frequency end

The abstract supertype for all frequencies.

See also: Unit and YPFrequency

struct HalfYearly{end_month} <: YPFrequency{2} end

A concrete frequency defined as 2 periods per year.

MIT{F <: Frequency}, Duration{F <: Frequency}

Two types representing a moment in time (like 2020Q1 or 2020Y) and duration (the quantity of time between two moments).

Both of these have a Frequency as a type parameter and both internally are represented by integer values.

If you imagine a time axis of the given Frequency, MIT values are ordinal (correspond to points) while Duration values are cardinal (correspond to distances).

MIT{F}(year, period) where {F <: YPFrequency}

Construct an MIT instance from year and period. This is valid only for frequencies subtyped from YPFrequency.

mutable struct MVTSeries{F,T,C} <: AbstractMatrix{T}
    firstdate::MIT{F}
    columns::OrderedDict{Symbol,TSeries{F,T}}
    values::C
end

Multi-variate Time series with frequency F with values of type T stored in a container of type C. By default the type is Float64 and the container is Matrix{Float64}. The rows correspond to moments in time and the columns correspond to variables. Columns are named. The values in the field columns are TSeries whose storages are views into the corresponding columns of the values matrix.

Construction:

x = MVTSeries(args...)

The standard construction is MVTSeries(firstdate::MIT, names, values) Here names should be a tuple of Symbols and values should be a matrix of the same number of columns as there are names in names. The range of the MVTSeries is determined from the number of rows of values. If values is not provided, the MVTSeries is constructed empty with size (0, length(names)). Ifnamesis also not provided, theMVTSeriesis constructed empty with size(0, 0)`.

The first argument can be a range. MVTSeries(range::AbstractUnitRange{<:MIT}, names, values) In this case the size of the MVTSeries is determined by the lengths of range and names; the values argument is interpreted as an initializer. If it is omitted or set to undef, the storage is left uninitialized. If it is a number, the storage is filled with it. It can also be an initializer function, such as zeros, ones or rand. Lastly, if the values argument is an array, it must be 2-dimensional and of the correct size.

Another possibility is to construct from a collection of name-value pairs. MVTSeries(range; var1 = val1, var2 = val2, ...) The range argument is optional, if missing it'll be determined from the ranges of the given values. The values can be TSeries, vectors or constants. Any vector must have the same length as the range.

An MVTSeries can also be constructed with copy, similar, and fill.

Indexing:

Indexing with integers, integer ranges, or boolean arrays works the same as with Matrix. The result from slicing with integer ranges or boolean arrays is always a Matrix, i.e., the MVTSeries structure is lost.

Indexing with two indexes works as follows. The first index can be an MIT or a range of MIT and it works the same as for TSeries. The second index can be a Symbol or a collection of Symbols, such as a tuple or a vector. begin and end work for the first index the same as with TSeries.

Indexing with one index depends on the type. If it is MIT or a range of MIT, it is treated as if the second index were :, i.e., the entire row or multiple rows is returned. If the index is a Symbol or a collection of Symbols, it is treated as if the first index were :, i.e., entire column or multiple columns is returned as TSeries or MVTSeries respectively.

Columns can also be accessed using "dot" notation. For example x[:a] is the same as x.a.

Check out the tutorial at https://bankofcanada.github.io/DocsEcon.jl/dev/Tutorials/TimeSeriesEcon/main/

struct Monthly <: YPFrequency{12} end

A concrete frequency defined as 12 periods per year.

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

struct Quarterly{end_month} <: YPFrequency{4} end

A concrete frequency defined as 4 periods per year. The default end_month is 3.

mutable struct TSeries{F, T, C} <: AbstractVector{T}
    firstdate::MIT{F}
    values::C
end

Time series with frequency F and values of type T stored in a container of type C. By default the type is Float64 and the container is Vector{Float64}.

Construction:

ts = TSeries(args...)

The standard construction is TSeries(firstdate::MIT, values::AbstractVector). If the second argument is not given, the TSeries is constructed empty.

Alternatively, the first argument can be a range. In this case, the second argument is interpreted as an initializer. If it is omitted or set to undef, the storage is left uninitialized. If it is a number, the storage is filled with it. It can also be an initializer function, such as zeros, ones or rand. Lastly, if the second argument is an array, it must be 1-dimensional and of the same length as the range given in the first argument.

If only an integer number is given, as in TSeries(n::Integer), the constructed TSeries will have frequency Unit, first date 1U and length n. An initialization argument is not allowed in this case, so the storage remains uninitialized.

A TSeries can also be constructed with copy, similar, and fill, ones, zeros.

Indexing:

Indexing with an MIT or a range of MIT works as you'd expect.

Indexing with Integers works the same as with Vector.

Indexing with Bool-array works as you'd expect. For example, s[s .< 0.0] .*= -1 multiplies in place the negative entries of s by -1, so effectively it's the same as s .= abs.(s).

There are important differences between indexing with MIT and not using MIT (i.e., using Integer or Bool-array).

• with MIT-range we return a TSeries, otherwise we return a Vector.

• the range can be extended (the TSeries resized appropriately) by assigning outside the current range. This works only with MIT. With anything else you get a BoundsError if you try to assign outside the Integer range.

• begin and end are MIT, so either use both or none of them. For example s[2:end] doesn't work because 2 is an Int and end is an MIT. You should use s[begin+1:end].

Check out the tutorial at https://bankofcanada.github.io/DocsEcon.jl/dev/Tutorials/TimeSeriesEcon/main/

struct Unit <: Frequency end

Represents a non-dimensional frequency (not associated with the calendar).

See also: Frequency, YPFrequency

struct Weekly{end_day} <: Frequency end

Represents a weekly frequency. The default weekly series ends on a Sunday (end_day = 7).

See also: Frequency

struct Workspace
    …
end

A collection of variables. Workspaces can store data of any kind, including numbers, MITs, ranges, strings, TSeries, MVTSeries, even nested Workspaces.

Construction

Easiest is to start with and empty Workspace and fill it up later. Otherwise, content can be provided at construction time as a collection of name-value pairs, where the name must be a Symbol and the value can be anything.

Access

Members of the Workspace can be accessed using "dot" notation or using [] indexing, like a dictionary.

Convenience constants that make MIT literal constants possible. For example, the constant Q1 makes it possible to write 2020Q1 instead of MIT{Quarterly}(2020, 1). Use U for MIT{Unit}, Y for MIT{Yearly}, Q1 to Q4 for MIT{Quarterly} and M1 to M12 for MIT{Monthly}

abstract type YPFrequency{N} <: Frequency end

Represents a calendar frequency defined by a number of periods in a year. The type parameter N is the number of periods and must be a positive integer.

See also: Frequency, Yearly, HalfYearly, Quarterly, Monthly

struct Yearly{end_month} <: YPFrequency{1} end

A concrete frequency defined as 1 period per year. The default end_month is 12.

apct(x::TSeries, islog::Bool)

Annualised percent rate of change in x.

Examples

julia> x = TSeries(qq(2018, 1), Vector(1:8));

julia> apct(x)
TSeries{Quarterly{3}} of length 7
2018Q2: 1500.0
2018Q3: 406.25
2018Q4: 216.04938271604937
2019Q1: 144.140625
2019Q2: 107.35999999999999
2019Q3: 85.26234567901243
2019Q4: 70.59558517284461

See also: pct

bdaily(d::Date; bias_previous::Bool=true)

Construct an MIT{BDaily} from a Date object.

The optional bias_previous argument determines which side of a weekend to land on when the provided date is Saturday or Sunday. The default is true, meaning that the preceding Friday is returned.

bdaily(d::String; bias_previous::Bool=true)

Construct an MIT{BDaily} from a String. The string must be convertible to a Date via the Dates.Date(d::String) method.

The optional bias_previous argument determines which side of a weekend to land on when the provided date is Saturday or Sunday. The default is true, meaning that the preceding Friday is returned.

clean_old_frequencies!

Like clean_old_frequencies, but in place.

clean_old_frequencies(m::MIT)
clean_old_frequencies(ts::TSeries)
clean_old_frequencies(mvts::MVTSeries)
clean_old_frequencies(ws::Workspace)
clean_old_frequencies!(ws::Workspace)

The internal representation for Quarterly and Yearly frequencies has changed between v0.4 and v0.5 of the TimeSeriesEcon package. Some stored data from old frequencies may need to be processed after loading to convert the objects to ones using the new frequencies.

Example: using JLD2 ws = Workspace(load("storedworkspace.jld2")) TimeSeriesEcon.cleanold_frequencies!(ws)

cleanedvalues(t::MVTSeries{BDaily}; skip_all_nans::Bool=false, skip_holidays::Bool=false, holidays_map::Union{Nothing, TSeries{BDaily}} = nothing)

Returns a matrix of values of a BDaily MVTSeries filtered according to the provided optional arguments. 
By default, all values are returned.

Optional arguments:
* `skip_all_nans` : When `true`, returns all rows for which none of the values are NaN. Displays a warning if rows are removed where some of the values are not Nan. Default is `false`.
* `skip_holidays` : When `true`, returns all rows which do not fall on a holiday according to the holidays map set in TimeSeriesEcon.getoption(:bdaily_holidays_map). Default: `false`.
* `holidays_map`  : Returns all rows that do not fall on a holiday according to the provided map which must be a BDaily TSeries of Booleans. Default is `nothing`.

cleanedvalues(t::TSeries{BDaily}; skip_all_nans::Bool=false, skip_holidays::Bool=false, holidays_map::Union{Nothing, TSeries{BDaily}} = nothing)

Returns the values of a BDaily TSeries filtered according to the provided optional arguments. By default, all values are returned.

Optional arguments:
* `skip_all_nans` : When `true`, returns all values which are not NaN values. Default is `false`.
* `skip_holidays` : When `true`, returns all values which do not fall on a holiday according to the holidays map set in TimeSeriesEcon.getoption(:bdaily_holidays_map). Default: `false`.
* `holidays_map`  : Returns all values that do not fall on a holiday according to the provided map which must be a BDaily TSeries of Booleans. Default is `nothing`.

colnames(x::MVTSeries)

Return the names of the columns of x as an iterable.

columns(x::MVTSeries)

Return the columns of x as a dictionary.

@compare x y [options] compare(x, y [; options])

Compare two Workspace recursively and print out the differences. MVTSeries and Dict with keys of type Symbol are treated like Workspace. TSeries and other Vector are compared using isapprox, so feel free to supply rtol or atol.

Optional argument name can be used for the top name. Default is "_".

Parameter showequal=true causes the report to include objects that are the same. Default behaviour, with showequal=false, is to report only the differences.

Parameter ignoremissing=true causes objects that appear in one but not the other workspace to be ignored. That is, they are not printed and do not affect the return value true or false. Default is ignoremissing=false meaning they will be printed and return value will be false.

daily(d::Date)

Convert a Date object to an MIT{Daily}.

daily(d::String)

Convert a String object to an MIT{Daily}. The string must be convertible to a Date via the Dates.Date(d::String) method.

divide_uneven(x::AbstractArray{<:Number}, inner::Vector{<:Integer})

Returns a vector of length length(x) * sum(inner) where each value in x is divided by the the same-index position value in the vector inner and the resulting value is repeated a number of times equal to the inner value.

Example: > divide_uneven([1,2,4], [2,1,4]) [0.5, 0.5, 2.0, 1, 1, 1, 1]

extend_series(F_to::Type{<:Frequency}, ts::TSeries; direction=:both, method=:mean)

This function pads the ends of a series to match a given frequency. An example would be extending a BDaily
TSeries to the ends of the Quarters in which the end dates fall. There are two keyword arguments:

* `method` - Determines the value to use in the extension. Default is the `:mean`, which will use the mean of the 
    existing values in the given period. The other available option is `:end` which will use the first value when
    extending the start of a series and the last value when extending the end of a series.

fconvert(F_to, MIT_from::MIT)

Convert the time MIT MIT_from to the desired frequency F_to.

fconvert(F_to, range_from::UnitRange{MIT})

Convert the time MIT MIT_from to the desired frequency F_to.

fconvert(F_to::Type{<:Union{<YPFrequency,<:CalendarFrequency}}, t::TSeries{<:Union{<YPFrequency,<:CalendarFrequency}}; method = :const, ref = :end)

Convert the time series t to the frequency F_to.

Converting to Higher Frequency

The only method available is method=:const, where the value at each period of the higher frequency is the value of the period of the lower frequency it belongs to.

x = TSeries(2000Q1:2000Q3, collect(Float64, 1:3))
fconvert(Monthly, x)

Converting to Lower or similar frequency

There are five methods available: :point, :mean, :sum, :min, and :max. The default is :mean. Each MIT in the input frequency will be mapped to the output MIT within which the start/end date of the input MIT falls - depending on the whether ref is :begin or :end. The corresponding values are then grouped for each output MIT and a value is determined based on the method.

• :mean: the values within each group are averaged.
• :sum: the values within each group are summed.
• :min: the lowest value within each group is chosen.
• :max: the highest value within each group is chosen.
• :point: see below.

Output ranges are truncated such that each output MIT contains a full complement of input values. For example, when ref is :end, an output MIT will be included if all MITs in the input frequency with end dates covered by the output frequency have values. Similarly, when ref is :begin an output MIT will be included if all input MITs with start dates covered by the output MIT have values.

The approach is different when method is :point. The output MIT will contain the value from the input MIT whose first/last day falls on or before the first/last day of the output MIT, depending on the ref argument. Truncation is more generous than with the other methods. When ref is :begin an output MIT will be included whenever an input MIT with a value overlaps the start_day of the output MIT. WHen ref is :end an output MIT will be included whenever there is a value from the input MIT whose end date is either on the last day of the output MIT, or whose end date is the closest to, but not after the last day of the output MIT.

Both method and ref are ignored when converting from Daily to BDaily.

Note that the approach taken here is not always precise. Because the values in the input trange are grouped by MITs in the output frequency, without any further accounting for transitions and relative sizes of input and output frequencies there may be some loss of accuracy. When more accuracy is desired, it is recommended to first convert the input tseries to Monthly or Daily frequency, before converting it to the desired output frequency.

Converting to Higher frequency

There are two methods available: :const and :even. Each MIT in the input range is mapped to one or more MITs in the output frequency. The value assigned to these output MITs depends on the method.

• :const : the input values is assigned to each corresponding output MIT.
• :even : the input value is divided evenly across corresponding output MITs.

The :linear method is additionally available when converting a lower frequency to Daily, BDaily, or Monthly. When method is :linear values are interpolated in a linear fashion across days/business days/months between input frequency periods. The specifics depends on ref. When ref is :end the values will be interpolated between the end-dates of adjacent periods. When ref = :begin the values will be interpolated between start-dates of adjacent periods. Tail-end periods will have values interpolated based on the progression in the adjacent non-tail-end period.

Passing a custom conversion function

One can also pass a custom function as the first argument of the fconvert command. These must have a particular input and output:

Converting to a lower frequency: The function must accept a single argument, a vector of values, and return a single value.

Converting to a higher frequency: The function must accept two positional arguments and any number of keyword arguments. The first positional argument will receive the vector of values from the input TSeries. The second positional argument is a vector of integers listing the number of output periods, which correspond to each input value. All keyword arguments are passed on to this conversion. In addition, the keyword argument outrange will be passed to the function. This argument provides the range of the resulting TSeries and can be useful if the function requires that one or more indicator series of the output frequency are passed.

x = TSeries(2000M1:2000M7, collect(Float64, 1:7))
fconvert(Quarterly, x; method = :sum)
fconvert(Daily, x; method = :const)

fconvert(F_to, t::TSeries)

Convert the time series t to the desired frequency F_to.

firstdate(x)

Return the first date of the range of allocated storage for the given TSeries or MVTSeries instance.

frequencyof(x)
frequencyof(T)

Return the Frequency type of the given value x or type T.

istypenan(x)

Return true if the given x is a not-n-number of its type, otherwise return false.

lag(x::TSeries, k=1)

Shift the dates of x by k period to produce the k-th lag of x. This is the same shift(x, -k).

lag!(x::TSeries, k=1)

In-place version of lag

lastdate(x)

Return the last date of the range of allocated storage for the given TSeries or MVTSeries instance.

lead(x::TSeries, k=1)

Shift the dates of x by k period to produce the k-th lead of x. This is the same shift(x, k).

lead!(x::TSeries, k=1)

In-place version of lead

mit2yp(x::MIT)

Recover the year and period from the given MIT value. This is valid only for frequencies subtyped from YPFrequency.

moving(x, n)

Compute the moving average of x over a window of n periods. If n > 0 the window is backward-looking (-n+1:0) and if n < 0 the window is forward-looking (0:-n-1).

overlay(arg1, args...)

Return the first argument, from left to right, that is valid. At least one argument must be given. Validity is determined by calling istypenan. If it returns true, the observation is not valid; false means it is.

overlay(data::MVTSeries, datan::MVTSeries...)

When all arguments are MVTSeries the result is an MVTSeries of the overlayed range and the ordered union of the columns. Each column is an overlay of the corresponding TSeries.

overlay([rng,] t1, t2, ...)

Construct a TSeries in which each observation is taken from the first valid observation in the list of arguments. A valid observation is one for which istypenan returns false.

All TSeries in the arguments list must be of the same frequency. The data type of the resulting TSeries is decided by the standard promotion of numerical types in Julia. Its range is the union of the ranges of the arguments, unless the optional rng is ginven in which case it becomes the range.

overlay(data1, data2, ...)

When overlaying Workspaces and MVTSeries the result is a Workspace and each member is overlaid recursively.

pct(x; islog=false)

Observation-to-observation percent rate of change in x.

period(mit)

Return the period of an MIT. This is valid only for frequencies subtyped from YPFrequency.

ppy(x)
ppy(T)

Return the periods per year for the frequency associated with the given value x or type T.

It returns approximations for CalendarFrequencies. Used in part for comparing frequencies.

YPFrequency.

rangeof(s)

Return the stored range of the given TSeries or MVTSeries instance.

rangeof(s; drop::Integer)

Return the stored range of s adjusted by dropping drop periods. If drop is positive, we drop from the beginning and if drop is negative we drop from the end. This adds convenience when using @rec

Example

julia> q = TSeries(20Q1:21Q4);
julia> rangeof(q; drop=1)
20Q2:21Q4

julia> rangeof(q; drop=-4)
20Q1:20Q4

julia> q[begin:begin+1] .= 1;
julia> @rec rangeof(q; drop=2) q[t] = q[t-1] + q[t-2];
julia> q
8-element TSeries{Quarterly{3}} with range 20Q1:21Q4:
    20Q1 : 1.0
    20Q2 : 1.0
    20Q3 : 2.0
    20Q4 : 3.0
    21Q1 : 5.0
    21Q2 : 8.0
    21Q3 : 13.0
    21Q4 : 21.0

rangeof(w)

Calculate the range of a Workspace as the intersection of the ranges of all TSeries, MVTSeries and Workspace members of w. If there are objects of different frequencies there will be a mixed-frequency error.

rawdata(t)

Return the raw storage of t. For a TSeries this is a Vector. For an MVTSeries this is a Matrix.

reindex(ts, from => to; copy = false)
reindex(w, from => to; copy = false)
reindex(rng, from => to)

The function reindex re-indexes the TSeries or MVTSeries ts, or those contained in the Workspace w, or the UnitRange rng, so that the MIT from becomes the MIT to leaving the data unchanged. For a Workspace, only objects with the same frequency as the first element of the pair will be reindexed; also, nested Workspaces are reindexed recursively.

By default, the data is not copied.

Example: With a TSeries or an MVTSeries

ts = MVTSeries(2020Q1,(:y1,:y2),randn(10,2))
ts2 = reindex(ts,2021Q1 => 1U; copy = true)
ts2.y2[3U] = 9999
ts
ts2

With a Workspace

w = Workspace();
w.a = TSeries(2020Q1,randn(10))
w.b = TSeries(2021Q1,randn(10))
w.c = 1
w.d = "string"
w1 = reindex(w, 2021Q1 => 1U)
w2 = reindex(w, 2021Q1 => 1U; copy = true)
w.a[2020Q1] = 9999
MVTSeries(; w1_a = w1.a, w2_a = w2.a)

reindex(2022Q4, 2022Q1 => 1U) === 4U

With a UnitRange

reindex(2021Q1:2022Q4, 2022Q1 => 1U)

repeat_uneven(x::AbstractArray{<:Number}, inner::Vector{<:Integer})

Returns a vector of length length(x) * sum(inner) where each value in x is repeated a number of times equal to the same-index position in the vector inner.

> repeat_uneven([1,2,4], [2,1,4]) [1, 1, 2, 4, 4, 4, 4]

sanitize_frequency(F::Frequency)

Return a concrete frequency type corresponding to the given, possibly abstract, frequency type. If F is already a concrete type, return F itself. Otherwise, if a default concrete frequency exists for the given abstract type, return that.

For example, the default Quarterly frequency is Quarterly{3}.

shift!(x::TSeries, n)
shift!(x::TSeries{BusinessDailies}, n, holidays_map=nothing)

In-place version of shift.

shift(x::TSeries, n)

Shift the dates of x by n periods. By convention positive n gives the lead and negative n gives the lag. shift creates a new TSeries and copies the data over. See shift! for in-place version.

For example:

julia> shift(TSeries(2020Q1, 1:4), 1)
TSeries{Quarterly{3}} of length 4
2019Q4: 1.0
2020Q1: 2.0
2020Q2: 3.0
2020Q3: 4.0


julia> shift(TSeries(2020Q1, 1:4), -1)
TSeries{Quarterly{3}} of length 4
2020Q2: 1.0
2020Q3: 2.0
2020Q4: 3.0
2021Q1: 4.0

shift(x::TSeries{BDaily}, n, skip_all_nans::Bool=false, skip_holidays::Bool=false, holidays_map::Union{Nothing, TSeries{BDaily}}=nothing)

As shift but with behavor depending on the TimeSeriesEcon options :bdaily_skip_nans, :bdaily_skip_holidays and the optional holidays_map argument.

When skip_all_nans is true, any NaN values replaced with the nearest valid value. Replacements will come from later time periods when k >= 0 and from earlier time periods when k < 0.

When skip_all_nans is false but skip_holidays is true or a holidays_map is passed to the function, then NaN originating from Holidays will be replaced with the nearest valid value. Replacements will come from later time periods when k >= 0 and from earlier time periods when k < 0.

Options:

• skipallnans : A Boolean. Default is false.
• skip_holidays : A Boolean. Default is false.
• holidays_map : A Boolean-values BDaily TSeries with true values on days which are not holidays. Default is nothing.

Example:

julia> shift(TSeries(bdaily("2022-07-04"), [1,2,NaN,4]), 1, skip_all_nans=true)
4-element TSeries{TimeSeriesEcon.BDaily} with range 2022-07-01:2022-07-06:
2022-07-01 : 1.0
2022-07-04 : 2.0
2022-07-05 : 4.0
2022-07-06 : 4.0


julia> shift(TSeries(bdaily("2022-07-04"), [1,2,NaN,4]), -1, skip_all_nans=true)
4-element TSeries{TimeSeriesEcon.BDaily} with range 2022-07-05:2022-07-08:
2022-07-05 : 1.0
2022-07-06 : 2.0
2022-07-07 : 2.0
2022-07-08 : 4.0

strip!(t::TSeries)

Remove leading and training NaN from the given time series. This is done in-place.

strip!(w::Workspace; recursive=true)

Apply strip! to all TSeries members of the given workspace. This includes nested workspaces, unless recursive=false.

typenan(x)
typenan(T)

Return a value that indicates not-a-number of the same type as the given x or of the given type T.

For floating point types, this is NaN. For integer types, we use typemax(). This is not ideal, but it'll do for now.

If second argument is anchor_value::Number, assume the anchor date is firstdate(dvar)-1

If second argument is anchor_value::Number, assume the anchor date is firstdate(dvar)-1

undiff(dvar, [date => value])
undiff!(var, dvar; fromdate=firstdate(dvar)-1)

Inverse of diff, i.e. var remains unchanged under undiff!(var, diff(var)) or undiff(diff(var), firstdate(var)=>first(var)). This is the same as cumsum, but specific to time series.

In the case of undiff the second argument is an "anchor" Pair specifying a known value at some time period. Typically this will be the period just before the first date of dvar, but doesn't have to be. If the date falls outside the rangeof(dvar) we extend dvar with zeros as necessary. If missing, this argument defaults to firstdate(dvar)-1 => 0.

In the case of undiff!, the var argument provides the "anchor" value and the storage location for the result. The fromdate parameter specifies the date of the "anchor" and the anchor value is taken from var. See important note below.

The in-place version (undiff!) works only with TSeries. The other version (undiff) works with MVTSeries as well as TSeries. In the case of MVTSeries the anchor value must be a Vector, or a Martix with 1 row, of the same length as the number of columns of dvar.

undiff(dvar, [date => value])
undiff!(var, dvar; fromdate=firstdate(dvar)-1)

Inverse of diff, i.e. var remains unchanged under undiff!(var, diff(var)) or undiff(diff(var), firstdate(var)=>first(var)). This is the same as cumsum, but specific to time series.

In the case of undiff the second argument is an "anchor" Pair specifying a known value at some time period. Typically this will be the period just before the first date of dvar, but doesn't have to be. If the date falls outside the rangeof(dvar) we extend dvar with zeros as necessary. If missing, this argument defaults to firstdate(dvar)-1 => 0.

In the case of undiff!, the var argument provides the "anchor" value and the storage location for the result. The fromdate parameter specifies the date of the "anchor" and the anchor value is taken from var. See important note below.

The in-place version (undiff!) works only with TSeries. The other version (undiff) works with MVTSeries as well as TSeries. In the case of MVTSeries the anchor value must be a Vector, or a Martix with 1 row, of the same length as the number of columns of dvar.

If second argument is anchor_value::Vector, assume the anchor date is firstdate(dvar)-1

If second argument is a pair ad::MIT => av::TSeries, take the anchor value to be av[ad]

If second argument is anchor::TSeries, assume anchor date is firstdate(dvar)-1 and take value form anchor

weekly(d::Date) 
weekly(d::String)
weekly(d::Date, end_day::Integer)
weekly(d::String, end_day::Integer)

These functions return an MIT{Weekly} from a provided Date object or String. The String must be convertible to a Date object via the Dates.Date(d::String) method.

Returns an object of type MIT{Weekly{endday}} when the endday argument is provided.

year(mit)

Return the year of an MIT. This is valid only for frequencies subtyped from YPFrequency.

ytypct(x)

Year-to-year percent change in x.

bd_str(d, bias)

A macro which converts a string to an MIT{BDaily} or a UnitRange{MIT{BDaily}}.

The optional biasdetermines which business day is returned when the provided date is on a Saturday or Sunday. Available options are"n"or"next"for biasing the next business day, and "p", or "previous" for the next business day,"near"or"nearest"for biasing the nearest business day, and"s"or"strict"` in which case passing a day on a weekend will return an error.

To return a UnitRange, provide a single string with two dates separated by :. In this case the first date will be biased to the following business day and the second date will be biased to the previous business day. The bias argument cannot be provided when converting a range of dates.

Example: aprilfirst = bd"2022-04-01" secondweekofapril = bd"2022-04-04:2022-04-08"

@compare x y [options] compare(x, y [; options])

Compare two Workspace recursively and print out the differences. MVTSeries and Dict with keys of type Symbol are treated like Workspace. TSeries and other Vector are compared using isapprox, so feel free to supply rtol or atol.

Optional argument name can be used for the top name. Default is "_".

Parameter showequal=true causes the report to include objects that are the same. Default behaviour, with showequal=false, is to report only the differences.

Parameter ignoremissing=true causes objects that appear in one but not the other workspace to be ignored. That is, they are not printed and do not affect the return value true or false. Default is ignoremissing=false meaning they will be printed and return value will be false.

d_str(d)

A macro which converts a string to an MIT{Daily} or a UnitRange{MIT{Daily}}.

To return a UnitRange, provide a single string with two dates separated by :.

Example: christmas = d"2022-12-25" daysoffebruary = d"2022-02-01:2022-02-28"

@rec [index=]range expression

Compute recursive operations on time series. The first argument is the range and the second argument is an expression to be evaluated over that range.

The expression is meant to be an assignment, but it doesn't have to be.

The range specification can include an optional indexing variable name. If not given, the variable name defaults to t.

Examples

julia> s = TSeries(1U)
Empty TSeries{Unit} starting 5U

julia> s[1U] = s[2U] = 1; s
2-element TSeries{Unit} with range 1U:2U:
      1U : 1.0
      2U : 1.0

julia> @rec t=3U:10U s[t] = s[t-1] + s[t-2]

julia> s
10-element TSeries{Unit} with range 1U:10U:
      1U : 1.0
      2U : 1.0
      3U : 2.0
      4U : 3.0
      5U : 5.0
      6U : 8.0
      7U : 13.0
      8U : 21.0
      9U : 34.0
     10U : 55.0

@showall X

Print all data in X without truncating the output to fit the size of the screen.

w_str(d)

A macro which converts a string to an MIT{Weekly{7}} or a UnitRange{MIT{Weekly{7}}}.

To return a UnitRange, provide a single string with two dates separated by :.

The resulting week(s) will be the week(s) containing the provided date(s).

Example: weekofchristmas = w"2022-12-25" weekoverlappingwith_february = w"2022-02-01:2022-02-28"

@weval W expression

Evaluate an expression using the members of Workspace W as if they were variables.

const root_id

The object id of the "/" catalog.

struct DEFile ... end

An instance of a *.daec file. Usually there's no need to create instances directly. Use opendaec and closedaec!.

closedaec!(de)

Close a .daec file that was previously opened with opendaec. The given instance of DEFile is modified in place to mark it as closed.

delete_object(de, object_id)

Delete the object with the given object_id from the file. It is an error to pass the id of an object that doesn't exist.

When an object is deleted, all its data and attributes are also deleted. If the object is a catalog, all objects in it are also deleted, including all nested catalogs are deleted recursively.

It is an error, and impossible, to delete the "/" (root_id) catalog. If you want to delete all objects in a file, use truncatedaec

find_fullpath(de, fullpath, error=true)

Find the object id of the object at the given path. The path must begin with '/', spell out all catalogs along the way, separated by '/', and name the object in the end.

The third argument, if given, controls what happens if the object doesn't exist.

• error=true directs find_fullpath to throw an exception.
• error=false directs find_fullpath to return missing.

See also find_object

find_object(de, parent_id, name, error=true)

Find and return the object id of the object identified by the given parent catalog and name. The parent catalog parent_id can be set to root_id, or to the id of a catalog obtained some other way, e.g., from new_catalog or find_fullpath. The name of the object can be a string or a Symbol. It must be the plain name, i.e. not containing any '/'.

The fourth argument, if given, controls what happens if the object doesn't exist.

• error=true directs find_object to throw an exception.
• error=false directs find_object to return missing.

See also find_fullpath

get_attribute(de, object_id, attr_name)

Retrieve the value of the named attribute for the object with the given id. The return value is either a String or missing.

get_fullpath(de, object_id)

Retrieve the full path of the object with the given id. The returned value is a String, unless the object doesn't exist, in which case get_fullpath throws an exception.

load_mvtseries(de, id)
load_mvtseries(de, fullpath)
load_mvtseries(de, parent, name)

Load an object of class class_mvtseries from the given .daec file de.

The object can be specified by its id, or by its full name. The full name can be given as a fullpath or as a parent and a name separately. IF given separately, the parent can be specified as an id or fullpath.

Throws an exception if the object doesn't exist, or if the object's class is not class_mvtseries.

The return value is a Julia object of an appropriate type.

load_scalar(de, id)
load_scalar(de, fullpath)
load_scalar(de, parent, name)

Load an object of class class_scalar from the given .daec file de.

The object can be specified by its id, or by its full name. The full name can be given as a fullpath or as a parent and a name separately. IF given separately, the parent can be specified as an id or fullpath.

Throws an exception if the object doesn't exist, or if the object's class is not class_scalar.

The return value is a Julia object of an appropriate type.

load_tseries(de, id)
load_tseries(de, fullpath)
load_tseries(de, parent, name)

Load an object of class class_tseries from the given .daec file de.

The object can be specified by its id, or by its full name. The full name can be given as a fullpath or as a parent and a name separately. IF given separately, the parent can be specified as an id or fullpath.

Throws an exception if the object doesn't exist, or if the object's class is not class_tseries.

The return value is a Julia object of an appropriate type.

de = opendaec(fname)
opendaec(fname) do de
    ...
end

Open the .daec file named in the given fname string and return an instance of DEFile. The version with the do-block automatically closes the file. Otherwise, call closedaec!.

read_data(de, id)
read_data(de, fullpath)
read_data(de, parent, name)

Load the specified object from the given .daec file de.

The object can be specified by its id, or by its full name. The full name can be given as a fullpath or as a parent and a name separately. If given separately, the parent can be specified as an id or fullpath.

Throws an exception if the object doesn't exist. Otherwise, if the object exists, read_data examines the class of the object and calls one of load_scalar, load_tseries, or load_mvtseries accordingly. That is unless the object has class class_catalog, then read_data returns a Workspace containing the objects in that catalog loaded by recursive calls to read_data.

The return value is a Julia object of an appropriate type.

readdb(de [, catalog])

Load all objects in a given catalog from the given .daec file and return them in a Workspace

If catalog is not given, it is assumed to be the root catalog, "/" or root_id. If given, it can be specified as an id, a fullpath, or a parent and a name separately. The specified object must exist and be of class class_catalog.

All object contained in the specified catalog are loaded by read_data.

set_attribute(de, object_id, attr_name, attr_value)

Write the given attribute for the object with the given id. If an attribute with the given name already exists, it is overwritten.

store_mvtseries(de, fullpath, value)
store_mvtseries(de, parent, name, value)

Create a new object with class class_mvtseries and write the given value for it in the .daec file de. The new object can be given either as a full path, or as a parent and a name separately. The value must be one of the Julia types that can be stored as a 2d array, for example MVTSeries, Matrix.

If the new object is named as a full path, all catalogs must already exist. This is the case also if given as parent and name separately - the parent must be either the full path to, or the id of, a catalog that already exists.

It is an error to name an object that already exists. In such case, call delete_object and try again.

store_scalar(de, fullpath, value)
store_scalar(de, parent, name, value)

Create a new object with class class_scalar and write the given value for it in the .daec file de. The new object can be given either as a full path, or as a parent and a name separately. The value must be one of the Julia types that can be stored as a scalar, for example numbers or strings.

If the new object is named as a full path, all catalogs must already exist. This is the case also if given as parent and name separately - the parent must be either the full path to, or the id of, a catalog that already exists.

It is an error to name an object that already exists. In such case, call delete_object and try again.

store_tseries(de, fullpath, value)
store_tseries(de, parent, name, value)

Create a new object with class class_tseries and write the given value for it in the .daec file de. The new object can be given either as a full path, or as a parent and a name separately. The value must be one of the Julia types that can be stored as a 1d array, for example TSeries, Vector, UnitRange.

If the new object is named as a full path, all catalogs must already exist. This is the case also if given as parent and name separately - the parent must be either the full path to, or the id of, a catalog that already exists.

It is an error to name an object that already exists. In such case, call delete_object and try again.

write_data(de, fullpath, value)
write_data(de, parent, name, value)

Create a new object with an appropriate class and write the given value for it in the given .daec file de. The new object can be given either as a full path, or as a parent and a name separately.

If the new object is specified as a full path, all catalogs must already exist. This is the case also if given as parent and name separately - the parent must be either the fullpath to, or the id of, a catalog that already exists.

It is an error to name an object that already exists. In such case, call delete_object and try again.

If data is a Workspace, it is stored as a new catalog with all members of data written in it recursively. Otherwise, write_data calls one of store_scalar, store_tseries, or store_mvtseries.

writedb(de, [parent,] data)

Write the given data into the given .daec file de. If parent catalog is specified (as a path or id), then the data is written in it, otherwise it is written in the root catalog.

The data must be a Workspace. Each nested Workspace is written in a sub-catalog recursively. All other values are written as objects of class class_scalar, class_tseries or class_mvtseries, as appropriate.

Any values that cannot be resolved as one of the object classes are skipped, with an error message issued accordingly, without throwing an exception.

See write_data.

Dates.Date(m::MIT, ref::Symbol=:end)

Returns a Date object representing the last day in the provided MIT. Returns the first day in the provided MIT when ref == true.

diff(x::TSeries)
diff(x::TSeries, k)

Construct the first difference, or the k-th difference, of time series t. If y = diff(x,k) then y[t] = x[t] - x[t+k]. A negative value of k means that we subtract a lag and positive value means that we subtract a lead. k not given is the same as k=-1, which matches the standard definition of first difference.

fill(val, range)
fill(val, range, variables)

In the first form create a TSeries with the given range. In the second form create an MVTSeries with the given range and variables. In both cases they are filled with the given value val.

pairs(data::MVTSeries; copy = false)

Returns an iterator over the named columns of data. Each iteration gives a name-value pair where name is a Symbol and value is a TSeries.

Setting copy=true is equivalent to pairs(copy(data)) but slightly more efficient.

resize!(t::TSeries, rng)

Extend or shrink the allocated storage for t so that the new range of t equals the given rng. If t is extended, new entries are set to NaN, or the appropriate Not-A-Number value (see typenan).

resize!(t::TSeries, n::Integer)

Extend or shrink the allocated storage for t to n entries. The first date of t does not change. If allocation is extended, the new entries are set to NaN.

similar(t::MVTSeries, [eltype], [shape])
similar(array, [eltype], shape)
similar(array_type, [eltype], shape)

Create an uninitialized MVTSeries with the given element type and shape.

If the first argument is an MVTSeries then the element type and shape of the output will match those of the input, unless they are explicitly given in subsequent arguments. If the first argument is another array or an array type, then shape must be given in the form of a tuple where the first element is an MIT range and the second is a list of column names. The element type, eltype, also can be given optionally; if not given it will be deduced from the first argument.

Example:

similar(Array{Float64}, (2000Q1:2001Q4, (:a, :b)))

similar(t::TSeries, [eltype], [range])
similar(array, [eltype], range)
similar(array_type, [eltype], range)

Create an uninitialized TSeries with the given element type and range.

If the first argument is a TSeries then the element type and range of the output will match those of the input, unless they are explicitly given in subsequent arguments. If the first argument is another array or an array type, then range must be given. The element type, eltype, can be given; if not it will be deduced from the first argument.

strip(t:TSeries)

Remove leading and trailing NaN from the given time series. This version creates a new TSeries instance.

_get_out_indices(F_to::Type{<:Union{Monthly, Quarterly{N1}, Quarterly, Yearly{N2}, Yearly, Weekly, Weekly{N3}}}, dates::Vector{Dates.Date})

Takes an array of dates and returns an array of MITs of the F_to frequency corresponding to each date.

clear_holidays_map()

Clears the current holidays map.

See also: get_holidays_options, set_holidays_map

fconvertparts(Fto::Type{<:Union{<:YPFrequency}}, MITfrom::MIT{<:Union{<:YPFrequency}}; ref=:end, checkparameterfrom=false, checkparameter_to=false)

This is a helper function used when converting TSeries or MIT UnitRanges between YPfrequencies. It provides the necessary component parts to make decisions about the completeness of the input tseries relative to the output frequency.

get_holidays_options(country::Union{String,Nothing}=nothing)

Returns a dictionary of country codes for supported countries and their subdivisions (where applicable)

Holiday calendars are produced using the python-holidays libary. See their site for more.

getoption(option::Symbol)

Returns the current value of the provided option.

See also setoption

mm(year, period)

Construct an MIT{Monthly} from an year and a period.

qq(year, period)

Construct an MIT{Quarterly} from an year and a period.

replace_nans_if_warranted!(ts::TSeries, k::Integer)

An internal function used to replace NaNs in a BDaily TSeries with their next or previous valid value. When skipholidays is true or a holidaysmap is passed the process only replaces NaNs when the source of the NaN is on a holiday.

set_holidays_map(country::String, subdivision::Union{String,Nothing}=nothing)

Sets the current holidays map to the given country and subdivision. Holiday maps span from 1970-01-01 to 2049-12-31.

See also: get_holidays_options, clear_holidays_map

setoption(option::Symbol, value)

Sets the provided option to the provided values.

Current available options are:

• :bdaily_holidays_map: This option holds a tseries of boolean values spanning from 1970-01-01 to 2049-12-31. Values on dates with a false entry will not be returned when calling the values function on a BDaily TSeries with the holidays=true option.
• :bdaily_skip_nans: This option controls the treatment of NaN values in BDaily arrays when performing shift, lag,diff, and pct functions on them. When true, NaNs are replaced with the most relevant non-NaN value when available.
• :bdaily_skip_holidays: When true, the values function will always be called with holidays=true for BDaily series. This also controls the behavior of the shift, lag, diff, and pct functions, but only NaNs falling on holidays are replaced.

skipifwarranted(x::AbstractArray{<:Number}, nans::Union{Bool,Nothing} = nothing)

Skips nans in a vector if either the provided nans option is true or if no nans option is
passed and the :bdaily_skip_nans option is true.

Returns the original vector otherwise.

yy(year, period)

Construct an MIT{Yearly} from an year and a period.

Base.empty!(de::DEFile)

Delete all objects in the given open .daec file.

new_catalog(de, fullpath)
new_catalog(de, parent, name)

Create a new object with class class_catalog in the given .daec file de. The new object can be specified either as a full path, or as a parent and a name separately.

If the new object is named as a full path, all catalogs in the path must already exist (except the last one, which is being created). This is the case also if given as parent and name separately - the parent must be either the full path to, or the id of, a catalog that already exists.

It is an error to name an object that already exists. In such case, call delete_object and try again.

struct DEError <: Exception
    ...
end

An exception type thrown by the "libdaec" C library. It contains a numerical code and a message.

Note that some errors thrown by the DataEcon module are of other exception types. This one is specifically for errors from the C library.