# FinanceCore

Documentation for FinanceCore.

FinanceCore.TimepointType
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
FinanceCore.CashflowType
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
FinanceCore.CompositeType
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
FinanceCore.PeriodicType
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

FinanceCore.PeriodicMethod
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

FinanceCore.QuoteType
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.

FinanceCore.RateMethod
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())

Base.:*Method
*(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.

Base.:+Method
+(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))
Base.:-Method
-(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))

Base.:/Method
/(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.

Base.:<Method
<(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
Base.:>Method
>(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
Base.convertMethod
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())
FinanceCore.amountMethod
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
FinanceCore.internal_rate_of_returnMethod
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.

FinanceCore.irrFunction
irr(cashflows::vector)
irr(cashflows::Vector, timepoints::Vector)

An alias for internal_rate_of_return.
FinanceCore.present_valueMethod
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
FinanceCore.rateMethod
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
FinanceCore.timepointMethod
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