FinanceModels.Bond API Reference

The Bond module provide a number of fixed-income contracts and related methods.

CMTYield(yield,maturity)
CMTYield(yield::Vector)

Returns a Quote for the correpsonding bond implied by the given bond equivalent yield, and assumes that instruments <= one year maturity` pay no coupons and that the rest pay semi-annual.

Use broadcasting to create a set of quotes given a collection of FinanceModels and maturities, e.g. CMTYield.(FinanceModels,maturities).

See also FinanceCore.Quote, Bond.Fixed

Examples

julia> CMTYield(0.05,10)
Quote{Float64, FinanceModels.Bond.Fixed{Periodic, Float64, Int64}}(1.0, FinanceModels.Bond.Fixed{Periodic, Float64, Int64}(0.05, Periodic(2), 10))

ParSwapYield(yield, maturity; frequency)

Same as ParYield for a par swap's fixed leg. frequency is required because fixed-leg conventions differ by market: annual for SOFR, €STR, and SONIA overnight index swaps, semiannual for legacy USD swaps and several government bond markets, and quarterly in some others. Pass an integer or a Periodic, e.g. ParSwapYield(0.04, 5; frequency = 1).

See also OISYield.

ParYield(yield, maturity; frequency=Periodic(2))
ParYield(yield::Rate{N,Periodic}, maturity; frequency=yield.compounding)

Create a Quote representing a par bond with the given yield and maturity. The default coupon frequency is semi-annual (Periodic(2)), the bond-equivalent convention of US Treasury par yields. A Rate with Periodic compounding sets the frequency itself; passing a different frequency with such a rate throws an ArgumentError. Convert the rate first, e.g. Periodic(1)(yield), to quote it at another frequency.

When maturity is not a whole number of coupon periods, the backward-anchored schedule (Bond.coupon_times) leaves a short first stub which accrues its actual length, and the coupon rate is solved so the bond prices to exactly 1.0 at the quoted yield: c·Σᵢ δᵢ·DF(tᵢ) + DF(T) = 1, where δ₁ = t₁ is the stub length and δᵢ = 1/frequency otherwise. The sub-period case (maturity ≤ 1/frequency) is the single-coupon instance of this rule: the stub pays accumulation(yield, maturity) - 1, so (1 + stub_coupon·maturity) * discount(yield, maturity) = 1.0. Otherwise, a standard par coupon bond Quote with price = 1.0 is returned.

Use broadcasting to create a set of quotes: ParYield.(yields, maturities).

Examples

julia> ParYield(0.05, 10)
Quote{Float64, FinanceModels.Bond.Fixed{Periodic, Float64, Int64}}(1.0, FinanceModels.Bond.Fixed{Periodic, Float64, Int64}(0.05, Periodic(2), 10))

julia> ParYield(Periodic(0.04, 2), 1//4)  # sub-period maturity → stub-period par bond
Quote{Float64, FinanceModels.Bond.Fixed{…}}(1.0, FinanceModels.Bond.Fixed{…}(…, Periodic(2), 1//4))

ZCBPrice(discount,maturity)
ZCBPrice(yield::Vector)

Takes spot/zero discount factors and returns a Quote for the cashflow occuring at the given maturity.

Use broadcasting to create a set of quotes given a collection of prices and maturities, e.g. ZCBPrice.(FinanceModels,maturities).

See also ZCBYield

Examples

julia> ZCBPrice(0.5,10)
Quote{Float64, Cashflow{Float64, Int64}}(0.5, Cashflow{Float64, Int64}(1.0, 10))

julia> ZCBPrice([0.9,0.8,0.75])
3-element Vector{Quote{Float64, Cashflow{Float64, Int64}}}:
 Quote{Float64, Cashflow{Float64, Int64}}(0.9, Cashflow{Float64, Int64}(1.0, 1))
 Quote{Float64, Cashflow{Float64, Int64}}(0.8, Cashflow{Float64, Int64}(1.0, 2))
 Quote{Float64, Cashflow{Float64, Int64}}(0.75, Cashflow{Float64, Int64}(1.0, 3))
 

ZCBYield(yield,maturity)
ZCBYield(yield::Vector)

Returns a Quote for the cashflow occuring at the given maturity and the quoted value is derived from the given yield.

Takes zero (sometimes called "spot") rates. Assumes annual effective compounding (Periodic(1)) unless given aRate` with a different compounding frequency.

Use broadcasting to create a set of quotes given a collection of FinanceModels and maturities, e.g. ZCBYield.(FinanceModels,maturities).

See also ZCBPrice

Examples

julia> ZCBYield(0.05,30)
Quote{Float64, Cashflow{Float64, Int64}}(0.23137744865585788, Cashflow{Float64, Int64}(1.0, 30))

julia> ZCBYield(Periodic(0.05,1),30)
Quote{Float64, Cashflow{Float64, Int64}}(0.23137744865585788, Cashflow{Float64, Int64}(1.0, 30))

julia> ZCBYield(Continuous(0.05),30)
Quote{Float64, Cashflow{Float64, Int64}}(0.22313016014842982, Cashflow{Float64, Int64}(1.0, 30))

julia> ZCBYield([0.04,0.05,0.045])
3-element Vector{Quote{Float64, Cashflow{Float64, Int64}}}:
 Quote{Float64, Cashflow{Float64, Int64}}(0.9615384615384615, Cashflow{Float64, Int64}(1.0, 1))
 Quote{Float64, Cashflow{Float64, Int64}}(0.9070294784580498, Cashflow{Float64, Int64}(1.0, 2))
 Quote{Float64, Cashflow{Float64, Int64}}(0.8762966040549094, Cashflow{Float64, Int64}(1.0, 3))

Bond.Fixed(coupon_rate,frequency<:FinanceCore.Frequency,maturity)

An object representing a fixed coupon bond. coupon_rate / frequency is the actual payment amount for each whole coupon period. A maturity that is not a whole number of periods produces a short first stub (the schedule anchors at maturity and counts backward — see Bond.coupon_times) which accrues its actual length: the first coupon is coupon_rate * t₁.

Note that there are a number of convienience constructors which return a Quote for a Bond.Fixed:

• ParYield
• ParSwapYield
• CMTYield
• OISYield

See also FinanceCore.Quote.

Examples

julia> Bond.Fixed(0.05,Periodic(2),3)
FinanceModels.Bond.Fixed{Periodic, Float64, Int64}(0.05, Periodic(2), 3)

julia> Bond.Fixed(0.05,Periodic(2),3) |> collect
6-element Vector{Cashflow{Float64, Float64}}:
 Cashflow{Float64, Float64}(0.025, 0.5)
 Cashflow{Float64, Float64}(0.025, 1.0)
 Cashflow{Float64, Float64}(0.025, 1.5)
 Cashflow{Float64, Float64}(0.025, 2.0)
 Cashflow{Float64, Float64}(0.025, 2.5)
 Cashflow{Float64, Float64}(1.025, 3.0)


julia> ParYield(0.05,10)
Quote{Float64, FinanceModels.Bond.Fixed{Periodic, Float64, Int64}}(1.0, FinanceModels.Bond.Fixed{Periodic, Float64, Int64}(0.05, Periodic(2), 10))

Bond.Floating(coupon_rate,frequency<:FinanceCore.Frequency,maturity,model_key)

An object representing a floating coupon bond. (coupon_rate + reference rate) / frequency is the actual payment amount for each whole coupon period, where the reference rate requires a Projection with a key/value pair where the key is the model_key argument and the value is the model which produces the reference rate. Coupons fix in advance over each accrual window. A maturity that is not a whole number of periods produces a short first stub (see Bond.coupon_times) which accrues its actual window [0, t₁]: the stub coupon is the reference curve's discount-factor ratio over the stub, minus one, plus coupon_rate * t₁ — it never references a time before issue.

See also FinanceCore.Quote.

Examples

julia> p = Projection(
        Bond.Floating(0.02, Periodic(1), 3.0, "SOFR"),
        Dict("SOFR" => Yield.Constant(0.05)),  # note the key/value store used for the model in the projection
        CashflowProjection(),
    );

julia> collect(p)
3-element Vector{Cashflow{Float64, Float64}}:
    Cashflow{Float64, Float64}(0.07000000000000005, 1.0)
    Cashflow{Float64, Float64}(0.07000000000000005, 2.0)
    Cashflow{Float64, Float64}(1.07, 3.0)

ForwardYield(yields,times)

Returns a vector of Quote corresponding to the yield at the given forward times.

Examples

julia> FinanceModels.Bond.ForwardYield([0.01,0.02],[1.,3.])
2-element Vector{Quote{Float64, Cashflow{Float64, Float64}}}:
 Quote{Float64, Cashflow{Float64, Float64}}(0.9900990099009901, Cashflow{Float64, Float64}(1.0, 1.0))
 Quote{Float64, Cashflow{Float64, Float64}}(0.9423223345470445, Cashflow{Float64, Float64}(1.0, 3.0))

OISYield(yield, maturity)

Returns the Quote implied by an overnight index swap rate yield for the given maturity. Maturities of one year or less settle once at maturity. Longer maturities pay annually on both legs, matching SOFR (Act/360), €STR (Act/360), and SONIA (Act/365F) overnight index swaps; the rate is quoted with annual compounding.

FinanceModels measures time in year fractions, so day counts are not modeled. A single-payment quote discounts at the annual-effective yield (discount(yield, maturity)); markets quote maturities under one year with simple interest, 1 / (1 + yield * maturity). The two agree at one year. Pass an equivalent annual-effective rate for shorter maturities if the difference matters.

Use broadcasting to create a set of quotes given a collection of FinanceModels and maturities, e.g. OISYield.(FinanceModels,maturities).

See also FinanceCore.Quote, Bond.Fixed

Examples

julia> OISYield(0.05,10)
Quote{Float64, FinanceModels.Bond.Fixed{Periodic, Float64, Int64}}(1.0, FinanceModels.Bond.Fixed{Periodic, Float64, Int64}(0.05, Periodic(1), 10))

__par_coupon(curve, maturity, frequency)

The annualized coupon rate c for which a fixed bond on the coupon_times schedule — first period accruing its actual length [0, t₁], whole 1/frequency periods thereafter — prices to par on curve: c·Σᵢ δᵢ·DF(tᵢ) + DF(T) = 1. curve may be a flat Rate or any yield model.

__regular_schedule(maturity, frequency)

Whether maturity is a whole number of 1/frequency coupon periods — i.e. the backward-anchored schedule from coupon_times starts a full period after issue and has no short first stub. Applies the same range-endpoint test coupon_times uses to decide whether to drop the terminal zero, so the two cannot disagree.

coupon_times(maturity, frequency)

Generate coupon times for a bond with the given maturity and frequency.

Arguments

• maturity::Real: The maturity of the bond.
• frequency::Real: The coupon frequency of the bond.

Returns

• An array of coupon times for the bond.

Examples

julia-repl julia> Bond.coupon_times(10, 2) 0.5:0.5:10.0 julia> Bond.coupon_times(Bond.Fixed(0.05,Periodic(4),20)) 0.25:0.25:20.0`