Fixed Income Treasury Securities

struct DiscreteCompoundingModel <: AbstractCompoundingModel

Immutable type that represents discrete compounding. This type has no fields and is passed as an argument to various functions to indicate that discrete compounding should be used in calculations.

struct ContinuousCompoundingModel <: AbstractCompoundingModel

Immutable type that represents continuous compounding. This type has no fields and is passed as an argument to various functions to indicate that continuous compounding should be used in calculations.

function discount(model::AbstractCompoundingModel, rate::Float64, periods::Int; λ::Int64 = 2)::Dict{Int,Float64}

The discount function computes the discount factors for a given compounding model. We assume that the discount rate is constant over all periods.

Arguments

• model::AbstractCompoundingModel: The compounding model to use to compute the discount factors. The model can be an instance of either a DiscreteCompoundingModel or a ContinuousCompoundingModel.
• rate::Float64: The annual discount rate used to compute the discount factors.
• periods::Int: The number of periods for which to compute the discount factors.
• λ::Int64: The number of compounding events per year. The default value is 2.

Returns

• Dict{Int,Float64}: A dictionary of the discount factors for the given compounding model. The keys are the period indexes and the values are the discount factors for 0 to periods.

mutable struct MyUSTreasuryZeroCouponBondModel <: AbstractTreasuryDebtSecurity

A mutable struct that represents a U.S. Treasury zero coupon security.

Fields

• par::Float64: The face or par value of the bond
• rate::Union{Nothing, Float64}: Effective annual interest rate (discount rate specified as a decimal)
• T::Union{Nothing,Float64}: Duration in years of the instrument, measured as a 365 day or a 52 week year
• n::Int: Number of compounding periods per year (typically 2)

Computed Fields

• price::Union{Nothing, Float64}: Price of the bond or note (computed property)
• cashflow::Union{Nothing, Dict{Int,Float64}}: Cashflow dictionary (computed property) where the key is the period and the value is the discounted cashflow in a period
• discount::Union{Nothing, Dict{Int,Float64}}: Discount factor dictionary (computed property) where the key is the period and the value is the discount factor in that period

mutable struct MyUSTreasuryCouponSecurityModel <: AbstractTreasuryDebtSecurity

A mutable struct that represents a U.S. Treasury coupon bond. This type of security (note or bond) pays the holder of the instrument a fixed interest rate at regular intervals over the life of the security.

Fields

• par::Float64: Par value of the bond
• rate::Union{Nothing, Float64}: Annualized effective discount rate
• coupon::Union{Nothing, Float64}: Coupon interest rate
• T::Union{Nothing,Float64}: Duration in years of the note or bond, measured as a 365 day or a 52 week year
• λ::Int: Number of coupon payments per year (typically 2)

Computed Fields

• price::Union{Nothing, Float64}: Price of the bond or note (computed property)
• cashflow::Union{Nothing, Dict{Int,Float64}}: Cashflow dictionary (computed property) where the key is the period and the value is the discounted cashflow in a period
• discount::Union{Nothing, Dict{Int,Float64}}: Discount factor dictionary(computed property) where the key is the period and the value is the discount factor in that period

function build(model::Type{MyUSTreasuryZeroCouponBondModel}, data::NamedTuple) -> MyUSTreasuryZeroCouponBondModel

This build method constructs an instance of the MyUSTreasuryZeroCouponBondModel type using the data in the NamedTuple argument.

Arguments

• model::Type{MyUSTreasuryZeroCouponBondModel}: The type of model to build.
• data::NamedTuple: The data to use to build the model.

The data::NamedTuple argument must contain the following keys:

• par::Float64: The face or par value of the bond
• rate::Union{Nothing, Float64}: Effective annual interest rate (discount rate specified as a decimal)
• T::Union{Nothing,Float64}: Duration in years measured as a 365 day or a 52 week year
• n::Int: Number of compounding periods per year (typically 2)

function build(model::Type{MyUSTreasuryCouponSecurityModel}, data::NamedTuple) -> MyUSTreasuryCouponSecurityModel

This build method constructs an instance of the MyUSTreasuryCouponSecurityModel type using the data in the NamedTuple.

Arguments

• model::Type{MyUSTreasuryCouponSecurityModel}: The type of model to build.
• data::NamedTuple: The data to use to build the model.

The data::NamedTuple must contain the following keys:

• par::Float64: Par value of the bond
• rate::Union{Nothing, Float64}: Annualized effective discount rate
• coupon::Union{Nothing, Float64}: Coupon interest rate
• T::Union{Nothing,Float64}: Duration in years of the note or bond, measured as a 365 day or a 52 week year
• λ::Int: Number of coupon payments per year (typically 2)

Return

This function returns an instance of the MyUSTreasuryCouponSecurityModel type. To populate the model, use the price function or a short-cut function involving a compounding model.

Example

Let's build a MyUSTreasuryCouponSecurityModel instance and populate the price, cashflow and discount datastructures for a T = 20-yr bond, with a coupon rate of c = 1.750%, a yield (discount rate) rate = 1.850%, two coupon payments per year, i.e., $\lambda = 2$ and a face (par) value of $V_{P}$ = 100 USD:

test_bond = build(MyUSTreasuryCouponSecurityModel, (
    T = 20.0, rate = 0.01850, coupon = 0.01750, λ = 2, par = 100.0
)) |> discount_model;

where the discount_model refers to either a DiscreteCompoundingModel or a ContinuousCompoundingModel instance.

function price(model::MyUSTreasuryCouponSecurityModel, compounding::T) -> MyUSTreasuryCouponSecurityModel where T <: AbstractCompoundingModel

The price(...) function computes the price of a MyUSTreasuryCouponSecurityModel instance using a discrete or continuous compounding model.

Arguments

• model::MyUSTreasuryCouponSecurityModel: an instance of the MyUSTreasuryCouponSecurityModel type.
• compounding::T: an instance of a type that is a subtype of AbstractCompoundingModel, i.e., a discrete or continuous compounding model.

Returns

• MyUSTreasuryCouponSecurityModel: an updated instance of the MyUSTreasuryCouponSecurityModel type with the price computed using the compounding model.

function price(model::MyUSTreasuryZeroCouponBondModel, compounding::T) -> MyUSTreasuryZeroCouponBondModel where T <: AbstractCompoundingModel

The price(...) function computes the price of a MyUSTreasuryZeroCouponBondModel instance using a discrete or continuous compounding model.

Arguments

• model::MyUSTreasuryZeroCouponBondModel: an instance of the MyUSTreasuryZeroCouponBondModel type.
• compounding::T: an instance of a type that is a subtype of AbstractCompoundingModel, i.e., a discrete or continuous compounding model.

Returns

• MyUSTreasuryZeroCouponBondModel: an updated instance of the MyUSTreasuryZeroCouponBondModel type with the price computed using the compounding model.

mutable struct MySymmetricBinaryInterestRateLatticeModel <: AbstractInterestRateTreeModel

The MySymmetricBinaryInterestRateLatticeModel mutable struct represents a binary lattice model for simulating interest rates.

Required fields

• u::Float64: The up-factor for the lattice
• d::Float64: The down-factor for the lattice
• p::Float64: The probability of an up move in the lattice
• rₒ::Float64: The initial interest rate (the root value of the lattice)
• T::Int64: The number of levels in the tree (zero based), so the tree will have a total of T + 1 levels (including the root level).

Computed fields

• connectivity::Union{Nothing,Dict{Int64, Array{Int64,1}}}: A dictionary that holds the connectivity of the lattice where the key is the node index and the value is an array of the connected nodes.
• levels::Union{Nothing,Dict{Int64,Array{Int64,1}}}: A dictionary that holds the node indexes on each level of the lattice where the key is the level index and the value is an array of the node indexes on that level.
• data::Union{Nothing, Dict{Int64, MyBinaryInterestRateLatticeNodeModel}}: A dictionary that holds the lattice data for each node where nodes are modeled as MyBinaryInterestRateLatticeNodeModel instances.

mutable struct MyBinaryInterestRateLatticeNodeModel

The MyBinaryInterestRateLatticeNodeModel mutable struct represents a node in a binary lattice model for simulating interest rates. This node type is created during the initialization of a lattice model and is used to store the probability, rate, and price data for each node.

Fields

• probability::Float64: The probability of reaching the node in the binary lattice
• rate::Float64: The interest rate at the node
• price::Float64: The price at the node (used for Treasury security pricing)

function build(model::Type{MySymmetricBinaryInterestRateLatticeModel}, data::NamedTuple) -> MySymmetricBinaryInterestRateLatticeModel

function populate(model::MySymmetricBinaryInterestRateLatticeModel) -> MySymmetricBinaryInterestRateLatticeModel

The populate function completes the initializing of a MySymmetricBinaryInterestRateLatticeModel model.

Arguments

• model::MySymmetricBinaryInterestRateLatticeModel: An instance of the MySymmetricBinaryInterestRateLatticeModel type constructed using the corresponding build function.

function expectation(model::MySymmetricBinaryInterestRateLatticeModel) -> Dict{Int64, Float64}

The expectation function computes the expectation for each tree level in the lattice model.

Arguments

• model::MySymmetricBinaryInterestRateLatticeModel: An instance of the MySymmetricBinaryInterestRateLatticeModel type constructed using the corresponding build and populate functions.

Returns

• Dict{Int64, Float64}: A dictionary where the key is the level index and the value is the expectation at that level.

function variance(model::MySymmetricBinaryInterestRateLatticeModel) -> Dict{Int64, Float64}

The variance function computes the variance for each tree level in the lattice model.

Arguments

• model::MySymmetricBinaryInterestRateLatticeModel: An instance of the MySymmetricBinaryInterestRateLatticeModel type constructed using the corresponding build and populate functions.

Returns

• Dict{Int64, Float64}: A dictionary where the key is the level index and the value is the variance at that level.

function strip(model::MyUSTreasuryCouponSecurityModel) -> Dict{Int, MyUSTreasuryZeroCouponBondModel}

Strips the coupon and par value payments from a parent coupon security.

The strip(...) function takes a model::MyUSTreasuryCouponSecurityModel of the security we wish to strip and returns a Dictionary holding MyUSTreasuryZeroCouponBondModel instances created from the parent security. The keys of the dictionary correspond to the temporal index of the created security.

function YTM(model::MyUSTreasuryZeroCouponBondModel, compounding::AbstractCompoundingModel; rₒ::Float64 = 0.01)::Float64

This function computes the Yield to Maturity (YTM) for a given bond model using the BFGS optimization algorithm. The YTM is the interest (discount) rate that minimizes the Net Present Value (NPV) of the zero coupon bond.

Arguments

• model::MyUSTreasuryZeroCouponBondModel: A zero coupon bond model that contains the bond data, sans the interest (discount) rate.
• compounding::AbstractCompoundingModel: The compounding model to use to compute the discount factors. The model can be an instance of either a DiscreteCompoundingModel or a ContinuousCompoundingModel.

Optional Arguments

• rₒ::Float64 = 0.01: The initial guess for the annual interest (discount) rate. The default value is 0.01.

Returns

• Float64: The annual interest (discount) rate that minimizes the NPV of the bond.