FinanceCore API Reference

Cashflow(amount,time)

A Cahflow{A,B} is a contract that pays an amount at time.

Cashflows can be:

• negated with the unary - operator.
• added/subtracted together but note that the time must be isapprox equal.
• multiplied/divided by a scalar.

Supertype Hierarchy ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

Cashflow{A<:Real, B<:Timepoint} <: FinanceCore.AbstractContract <: Any

Composite(A,B)

Summary ≡≡≡≡≡≡≡≡≡

struct Composite{A, B}

A Composite{A,B} is a contract that is composed of two other contracts of type A and type B. The maturity of the composite is the maximum of the maturities of the two components.

It is used to assemble arbitrarily complex contracts from simpler ones.

Fields ≡≡≡≡≡≡≡≡

a :: A
b :: B

Supertype Hierarchy ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

Composite{A, B} <: FinanceCore.AbstractContract <: Any

Continuous()

A type representing continuous interest compounding frequency.

Examples

julia> Rate(0.01,Continuous())
Rate(0.01, Continuous())

See also: Periodic

julia> Continuous(0.01)
Rate(0.01, Continuous())

See also: Periodic

Periodic(frequency)

A type representing periodic interest compounding with the given frequency.

frequency will be converted to an Integer, and will round up to 8 decimal places (otherwise will throw an InexactError).

Examples

Creating a semi-annual bond equivalent yield:

julia> Rate(0.01,Periodic(2))
Rate(0.01, Periodic(2))

See also: Continuous

Periodic(rate,frequency)

A convenience constructor for Rate(rate,Periodic(frequency)).

Examples

Creating a semi-annual bond equivalent yield:

julia> Periodic(0.01,2)
Rate(0.01, Periodic(2))

See also: Continuous

Quote(price,instrument)

The price(<:Real) is the observed value , and the instrument is the instrument/contract that the price is for.

This can be used, e.g., to calibrate a valuation model to prices for the given instruments - see FinanceModels.jl for more details.

Rate(rate[,frequency=1])
Rate(rate,frequency::Frequency)

Rate is a type that encapsulates an interest rate along with its compounding frequency.

Periodic rates can be constructed via Rate(rate,frequency) or Rate(rate,Periodic(frequency)). If not given a second argument, Rate(rate) is equivalent to Rate(rate,Periodic(1)).

Continuous rates can be constructed via Rate(rate, Inf) or Rate(rate,Continuous()).

Examples

julia> Rate(0.01,Continuous())
Rate(0.01, Continuous())

julia> Continuous(0.01)
Rate(0.01, Continuous())

julia> Continuous()(0.01)
Rate(0.01, Continuous())

julia> Rate(0.01,Periodic(2))
Rate(0.01, Periodic(2))

julia> Periodic(0.01,2)
Rate(0.01, Periodic(2))

julia> Periodic(2)(0.01)
Rate(0.01, Periodic(2))

julia> Rate(0.01)
Rate(0.01, Periodic(1))

julia> Rate(0.01,2)
Rate(0.01, Periodic(2))

julia> Rate(0.01,Periodic(4))
Rate(0.01, Periodic(4))

julia> Rate(0.01,Inf)
Rate(0.01, Continuous())

amount(x)

If is an object with an amount component (e.g. a Cashflow), will retrun that amount component, otherwise just x.

Examples

julia> FinanceCore.amount(Cashflow(1.,3.))
1.0

julia> FinanceCore.amount(1.)
1.0

internal_rate_of_return(cashflows::vector)::Rate
internal_rate_of_return(cashflows::Vector, timepoints::Vector)::Rate

Calculate the internalrateof_return with given timepoints. If no timepoints given, will assume that a series of equally spaced cashflows, assuming the first cashflow occurring at time zero and subsequent elements at time 1, 2, 3, ..., n.

Returns a Rate type with periodic compounding once per period (e.g. annual effective if the timepoints given represent years). Get the scalar rate by calling Yields.rate() on the result.

Example

julia> internal_rate_of_return([-100,110],[0,1]) # e.g. cashflows at time 0 and 1
0.10000000001652906
julia> internal_rate_of_return([-100,110]) # implied the same as above
0.10000000001652906

Solver notes

Will try to return a root within the range [-2,2]. If the fast solver does not find one matching this condition, then a more robust search will be performed over the [.99,2] range.

The solution returned will be in the range [-2,2], but may not be the one nearest zero. For a slightly slower, but more robust version, call ActuaryUtilities.irr_robust(cashflows,timepoints) directly.

irr(cashflows::vector)
irr(cashflows::Vector, timepoints::Vector)

An alias for `internal_rate_of_return`.

present_value(yield_model, cashflows[, timepoints=pairs(cashflows)])

Discount the cashflows vector at the given yield_model, with the cashflows occurring at the times specified in timepoints. If no timepoints given, assumes that cashflows happen at the indices of the cashflows.

If your timepoints are dates, you can convert them into a floating point representation of the time interval using DayCounts.jl.

Examples

julia> present_value(0.1, [10,20],[0,1])
28.18181818181818
julia> present_value(Continuous(0.1), [10,20],[0,1])
28.096748360719193
julia> present_value(Continuous(0.1), [10,20],[1,2])
25.422989241919232
julia> present_value(Continuous(0.1), [10,20])
25.422989241919232

rate(r::Rate)

Returns the untyped scalar interest rate represented by the Rate.

Examples

julia> r =Continuous(0.03)
Yields.Rate{Float64, Continuous}(0.03, Continuous())

julia> rate(r)
0.03

timepoint(x,t)

If x is an object with a defined time component (e.g. a Cashflow), will return that time component, otherwise will return t. This is useful in handling situations where you want to handle either Cashflows or separate amount and time vectors.

Example

julia> FinanceCore.timepoint(Cashflow(1.,3.),"ignored")
3.0

julia> FinanceCore.timepoint(1.,4.)
4.0

Timepoint(a)

Summary ≡≡≡≡≡≡≡≡≡

Timepoint is a type alias for Union{T,Dates.Date} that can be used to represent a point in time. It can be either a Dates.Date or a Real number. If defined as a real number, the interpretation is the number of (fractional) periods since time zero.

Currently, the usage of Dates.Date is not well supported across the JuliaActuary ecosystem but this type is in place such that it can be built upon further.

Supertype Hierarchy ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

Timepoint{T} = Union{T,Dates.Date} <: Any

*(Yields.Rate, T)
*(T, Yields.Rate)

The multiplication of a Rate with a scalar will inherit the type of the Rate, or the first argument's type if both are Rates.

+(Yields.Rate, T<:Real)
+(T<:Real, Yields.Rate)
+(Yields.Rate,Yields.Rate)

The addition of a rate with a number will inherit the type of the Rate, or the first argument's type if both are Rates.

Examples

julia> Yields.Periodic(0.01,2) + Yields.Periodic(0.04,2)
Yields.Rate{Float64, Yields.Periodic}(0.05000000000000004, Yields.Periodic(2))

julia> Yields.Periodic(0.04,2) + 0.01
Yields.Rate{Float64, Yields.Periodic}(0.05, Yields.Periodic(2))

-(Yields.Rate, T<:Real)
-(T<:Real, Yields.Rate)
-(Yields.Rate, Yields.Rate)

The addition of a rate with a number will inherit the type of the Rate, or the first argument's type if both are Rates.

Examples

julia> Yields.Periodic(0.04,2) - Yields.Periodic(0.01,2)
Yields.Rate{Float64, Yields.Periodic}(0.030000000000000214, Yields.Periodic(2))

julia> Yields.Periodic(0.04,2) - 0.01
Yields.Rate{Float64, Yields.Periodic}(0.03, Yields.Periodic(2))

/(x::Yields.Rate, y::Real)

The division of a Rate with a scalar will inherit the type of the Rate, or the first argument's type if both are Rates.

<(x::Rate,y::Rate)

Convert the second argument to the periodicity of the first and compare the scalar rate values to determine if the first argument has a lower force of interest than the second.

Examples

julia> Yields.Periodic(0.03,100) < Yields.Continuous(0.03)
true

>(Rate,Rate)

Convert the second argument to the periodicity of the first and compare the scalar rate values to determine if the first argument has a greater force of interest than the second.

Examples

julia> Yields.Periodic(0.03,100) > Yields.Continuous(0.03)
false

convert(cf::Frequency,r::Rate)

Returns a Rate with an equivalent discount but represented with a different compounding frequency.

Examples

julia> r = Rate(Periodic(12),0.01)
Rate(0.01, Periodic(12))

julia> convert(Periodic(1),r)
Rate(0.010045960887181016, Periodic(1))

julia> convert(Continuous(),r)
Rate(0.009995835646701251, Continuous())