FinanceModels API Reference

CashflowProjection()

A concrete subtype of ProjectionKind which is the projection which returns only a reducible collection of Cashflows. Use in conjunction with a Projection.

CommonEquity()

A singleton type representing a unit stock.

See also: Option.

Forward(time,instrument)

The instrument is relative to the Forward time. e.g. if you have a Forward(1.0, Cashflow(1.0, 3.0)) then the instrument is a cashflow that pays 1.0 at time 4.0

NullModel()

A singleton type representing a placeholder model for when you don't really need a model. For example: determining nominal cashflows for fixed income contract.

Projection(contract,model,kind)

The set of contracts and assumptions (model) to project the kind of output desired. Some assets require a projection in order to be valued (e.g. a floating rate bond).

If attempting to collect or otherwise reduce a contract (<:AbstractContract), by default it will get wrapped into a Projection(contract,NullModel(),CashflowProjection())

FinanceCore.internal_rate_of_return(q::Quote)

Return the internal rate of return (yield to maturity) implied by the quote's price and cashflows.

present_value(model,contract,current_time=0.0)
present_value(model,projection,current_time=0.0)

Return the value of the contract as corresponding with the valuation assumptions embedded in the model for the given contract or projection with CashflowProjection kind.

Examples

m = Equity.BlackScholesMerton(0.01, 0.02, 0.15)

a = Option.EuroCall(CommonEquity(), 1.0, 1.0)

pv(m, a) # ≈ 0.05410094201902403

InterestRateSwap(curve, tenor; model_key="OIS")

A convenience method for creating an interest rate swap given a curve and a tenor via a Composite contract consisting of receiving a fixed bond and paying (i.e. the negative of) a floating bond.

The notional is a unit (1.0) amount and assumed to settle four times per period.

A Projection, with an indexable model_key is still needed to project a swap. See examples below for what this looks like.

Examples

julia> curve = Yield.Constant(0.05);

julia> swap = InterestRateSwap(curve,10);

julia> Projection(swap,Dict("OIS" => curve),CashflowProjection()) |> collect
80-element Vector{Cashflow{Float64, Float64}}:
Cashflow{Float64, Float64}(0.012272234429039353, 0.25)
Cashflow{Float64, Float64}(0.012272234429039353, 0.5)
⋮
Cashflow{Float64, Float64}(-0.012272234429039353, 9.75)
Cashflow{Float64, Float64}(-1.0122722344290391, 10.0)

fit(
    model, 
    quotes, 
    method=Fit.Loss(x -> x^2);
    variables=__default_optic(model), 
    optimizer=__default_optim(model)
    )

Fit a model to a collection of quotes using a loss function and optimization method.

Arguments

• model: The initial model to fit, which is generally an instantiated but un-optimized model.
• quotes: A collection of quotes to fit the model to.
• method::F=Fit.Loss(x -> x^2): The loss function to use for fitting the model. Defaults to the squared loss function.
  • method can also be Bootstrap(). If this is the case, model should be a spline such as Spline.Linear(), Spline.Cubic()...
• variables=__default_optic(model): The variables to optimize over. This is a tuple of optic => interval pairs specifying which parameters of the model can vary. See extended help for more.
• optimizer=__default_optim(model): The optimization algorithm to use. The default optimization for a given model is LBFGS() from Optim.jl (via OptimizationOptimJL), a quasi-Newton method with automatic differentiation via ForwardDiff. See extended help for more on customizing the solver.

The optimization routine will then attempt to modify parameters of model to best fit the quoted prices of the contracts underlying the quotes by calling present_value(model,contract). The optimization will minimize the loss function specified within Fit.Loss(...).

Different types of quotes are appropriate for different kinds of models. For example, if you try to value a set of equtiy EuroCalls with a Yield.Constant, you will get an error because the present_value(m<:Yield.Constant,o<:EuroCall) is not defined.

Returns

• The fitted model.

Examples

julia> model = Yield.Constant();

julia> quotes = ZCBPrice([0.9, 0.8, 0.7,0.6]);

julia> fit(model,quotes)

              ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀Yield Curve (FinanceModels.Yield.Constant)⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀           
              ┌────────────────────────────────────────────────────────────┐           
     0.120649 │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│ Zero rates
              │⠀⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              │⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              │⠀⣧⢰⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              │⠀⣿⣾⠀⣀⣸⠀⢸⢳⣇⢀⣀⣀⣀⣀⣀⠀⡀⣀⣀⣀⡀⡀⣀⢀⣀⡀⡀⣀⢀⡀⣀⡀⢀⣀⡀⢀⡀⢀⣀⡀⢀⡀⠀⣀⡀⢀⡀⢀⣀⡀⢀⣀⠀⣀⡀⢀⣀⠀⢀│           
              │⢠⢻⡟⡆⣿⡟⣦⠚⠀⢸⣾⠛⠛⠘⠛⠘⢲⡗⠛⠃⠛⠓⠓⠛⠚⠛⠑⠓⠛⠃⠓⠛⠑⠚⡟⠓⢻⡗⠚⠀⠓⠚⠑⠒⠃⠓⠚⠑⠚⠀⠓⠃⠘⠒⠃⠓⠃⠘⠒⠃│           
              │⢸⢸⡇⢹⡏⠁⠉⠀⠀⠈⠉⠀⠀⠀⠀⠀⠀⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠁⠀⠈⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
   Continuous │⢸⢸⡇⢸⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              │⢸⠀⠁⢸⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              │⢸⠀⠀⠘⠇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              │⡎⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              │⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              │⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
     0.120649 │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│           
              └────────────────────────────────────────────────────────────┘           
              ⠀0⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀time⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀30⠀  

Extended help

Customizing the Solver

The default solver is LBFGS() from Optim.jl (via OptimizationOptimJL). This is a quasi-Newton method that uses automatic differentiation (ForwardDiff) to compute gradients efficiently.

• Any solver from OptimizationOptimJL can be used, e.g. fit(...; optimizer=OptimizationOptimJL.Newton()) or fit(...; optimizer=OptimizationOptimJL.NelderMead()).
• More documentation is available from the upstream packages:
  • Optim.jl
  • Optimization.jl
  • AccessibleModels.jl

Defining the variables

An arbitrarily complex model may be the object we intend to fit - how does fit know what free variables are able to be solved for within the given model? variables is a tuple of optic => interval pairs. What does this mean?

• An optic (or "lens") is a way to define an accessor to a given object. Example:

julia> using Accessors, AccessibleModels, IntervalSets

julia> obj = (a = "AA", b = "BB");

julia> lens = @optic _.a
(@optic _.a)

julia> lens(obj)
"AA"

An optic argument is a tuple of optic => interval pairs. For example, we might have a model as follows where we want fit to optimize parameters a and b:

struct MyModel <:FinanceModels.AbstractModel
     a 
     b 
end

__default_optic(m::MyModel) = (
    @optic(_.a) => 0.0 .. 100.0,
    @optic(_.b) => -10.0 .. 10.0,
)

In this way, fit know which arbitrary parameters in a given object may be modified. Technically, we are not modifying the immutable MyModel, but instead efficiently creating a new instance. This is enabled by AccessibleModels.jl.

Note that not all optimization algorithms want a bounded interval. In that case, simply leave off the paired range. The prior example would then become:

__default_optic(m::MyModel) = (
    (@optic(_.a),),
    (@optic(_.b),),
)

```

Additional Examples

See the tutorials in the package documentation for FinanceModels.jl or the docstrings of FinanceModels.jl's available model types.

abstract type ProjectionKind

An abstract type that controls what gets produced from the model.

Subtypes of ProjectionKind define the level of detail in the output of the model. For example, if you just want cashflows or you want a full amortization schedule, you might define an AmortizationSchedule kind which shows principle, interest, etc.

After defining a new ProjectionKind, you need to define the how the projection works for that new output by extending either:

function Transducers.asfoldable(p::Projection{C,M,K}) where {C<:Cashflow,M,K<:CashflowProjection}
    ...
end

or

function Transducers.__foldl__(rf, val, p::Projection{C,M,K}) where {C<:Cashflow,M,K<:CashflowProjection}
    ...
end

There are examples of this in the documentation.

Examples

```julia julia> struct CashflowProjection <: ProjectionKind end CashflowProjection

julia> struct AmortizationSchedule <: ProjectionKind end AmortizationSchedule

__default_optic(model)

Returns the variables to optimize over for the given model. This is an optic/lens specifying which parameters of the model can vary. See extended help for more. An optic argument is a tuple of optic => interval pairs specifying which model parameters to optimize and their bounds.

Examples

We might have a model as follows where we want fit to optize parameters a and b:

struct MyModel <:FinanceModels.AbstractModel
        a 
        b 
end

__default_optic(m::MyModel) = (
    @optic(_.a) => 0.0 .. 100.0,
    @optic(_.b) => -10.0 .. 10.0,
)

Extended help

An arbitrarily complex model may be the object we intend to fit - how does fit know what free variables are able to be solved for within the given model? variables is a tuple of optic => interval pairs. What does this mean?

• An optic (or "lens") is a way to define an accessor to a given object. Example:

julia> using Accessors, AccessibleModels, IntervalSets

julia> obj = (a = "AA", b = "BB");

julia> lens = @optic _.a
(@optic _.a)

julia> lens(obj)
"AA"

An optic argument is a tuple of optic => interval pairs. For example, we might have a model as follows where we want fit to optize parameters a and b:

struct MyModel <:FinanceModels.AbstractModel
        a 
        b 
end

__default_optic(m::MyModel) = (
    @optic(_.a) => 0.0 .. 100.0,
    @optic(_.b) => -10.0 .. 10.0,
)

In this way, fit know which arbitrary parameters in a given object may be modified. Technically, we are not modifying the immutable MyModel, but instead efficiently creating a new instance. This is enabled by AccessibleModels.jl.

Note that not all optimization algorithms want a bounded interval. In that case, simply leave off the paired range. The prior example would then become:

__default_optic(m::MyModel) = (
    (@optic(_.a),),
    (@optic(_.b),),
)

```

__rewrap(from::Transducers.Reduction, to)
__rewrap(from, to)

Used to unwrap a Reduction which is a composition of contracts and a transducer and apply the transducers to the associated projection instead of the transducer.

For example, on its own a contract is not project-able, but wrapped in a (default) Projection it can be. But it may also be a lot more convienent to construct contracts which have scaling or negated modifications and let that flow into a projection.

Examples

julia> Bond.Fixed(0.05,Periodic(1),3) |> collect
3-element Vector{Cashflow{Float64, Float64}}:
 Cashflow{Float64, Float64}(0.05, 1.0)
 Cashflow{Float64, Float64}(0.05, 2.0)
 Cashflow{Float64, Float64}(1.05, 3.0)

julia> Bond.Fixed(0.05,Periodic(1),3) |> Map(-) |> collect
3-element Vector{Cashflow{Float64, Float64}}:
 Cashflow{Float64, Float64}(-0.05, 1.0)
 Cashflow{Float64, Float64}(-0.05, 2.0)
 Cashflow{Float64, Float64}(-1.05, 3.0)

julia> Bond.Fixed(0.05,Periodic(1),3) |> Map(-) |> Map(x->x*2) |> collect
3-element Vector{Cashflow{Float64, Float64}}:
 Cashflow{Float64, Float64}(-0.1, 1.0)
 Cashflow{Float64, Float64}(-0.1, 2.0)
 Cashflow{Float64, Float64}(-2.1, 3.0)

cashflows_timepoints(contracts)
cashflows_timepoints(quotes)

Create a matrix of cashflows and a vector of timepoints for a collection of quotes or contracts. Timepoints need not be spaced evenly.

This is used when constructing SmithWilson yield curves.

Arguments

• contracts or quotes: A collection of <:AbstractContracts or Quotes.

Returns

• A tuple (m, times) where m is a matrix of cashflows and times is a vector of timepoints.

Examples

julia> FinanceModels.cashflows_timepoints(ParYield.([0.04,0.02,0.04],[1,4,4]))
([0.02 0.01 0.02; 1.02 0.01 0.02; … ; 0.0 0.01 0.02; 0.0 1.01 1.02], [0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0])

eurocall(;S=1.,K=1.,τ=1,r,σ,q=0.)

Calculate the Black-Scholes implied option price for a european call, where:

• S is the current asset price
• K is the strike or exercise price
• τ is the time remaining to maturity (can be typed with \tau[tab])
• r is the continuously compounded risk free rate
• σ is the (implied) volatility (can be typed with \sigma[tab])
• q is the continuously paid dividend rate

Rates should be input as rates (not percentages), e.g.: 0.05 instead of 5 for a rate of five percent.

!!! Experimental: this function is well-tested, but the derivatives functionality (API) may change in a future version of ActuaryUtilities.

Extended Help

This is the same as the formulation presented in the dividend extension of the BS model in Wikipedia.

Other general comments:

• Swap/OIS curves are generally better sources for r than government debt (e.g. US Treasury) due to the collateralized nature of swap instruments.
• (Implied) volatility is characterized by a curve that is a function of the strike price (among other things), so take care when using
• Yields.jl can assist with converting rates to continuously compounded if you need to perform conversions.

europut(;S=1.,K=1.,τ=1,r,σ,q=0.)

Calculate the Black-Scholes implied option price for a european call, where:

• S is the current asset price
• K is the strike or exercise price
• τ is the time remaining to maturity (can be typed with \tau[tab])
• r is the continuously compounded risk free rate
• σ is the (implied) volatility (can be typed with \sigma[tab])
• q is the continuously paid dividend rate

Rates should be input as rates (not percentages), e.g.: 0.05 instead of 5 for a rate of five percent.

!!! Experimental: this function is well-tested, but the derivatives functionality (API) may change in a future version of ActuaryUtilities.

Extended Help

This is the same as the formulation presented in the dividend extension of the BS model in Wikipedia.

Other general comments:

• Swap/OIS curves are generally better sources for r than government debt (e.g. US Treasury) due to the collateralized nature of swap instruments.
• (Implied) volatility is characterized by a curve that is a function of the strike price (among other things), so take care when using
• Yields.jl can assist with converting rates to continuously compounded if you need to perform conversions.