From d87a43a660c8dbc3f11fa118549c5d4f503064eb Mon Sep 17 00:00:00 2001 From: alecloudenback Date: Fri, 27 Oct 2023 22:02:28 -0500 Subject: [PATCH] Docs update to strict docs build (#164) * WIP docs update to strict docs build * more doc cleanup * strict build * last tweaks? --- docs/Project.toml | 1 + docs/docs/Project.toml | 4 ++ docs/make.jl | 27 ++++++++--- docs/src/API/Bond.md | 19 ++++++++ docs/src/API/Equity.md | 19 ++++++++ docs/src/API/FinanceCore.md | 19 ++++++++ docs/src/API/FinanceModels.md | 19 ++++++++ docs/src/API/Fit.md | 19 ++++++++ docs/src/API/Option.md | 19 ++++++++ docs/src/API/Spline.md | 19 ++++++++ docs/src/API/Volatility.md | 19 ++++++++ docs/src/API/Yield.md | 19 ++++++++ docs/src/Rates.md | 62 ++++++++++++++++++++++++++ docs/src/api.md | 43 ------------------ docs/src/contracts.md | 32 ++----------- docs/src/faq.md | 4 +- docs/src/index.md | 2 +- docs/src/{guide.md => introduction.md} | 4 +- docs/src/migration.md | 2 +- docs/src/models.md | 40 +++++++++-------- src/Contract.jl | 28 ++++++++++-- src/fit.jl | 22 ++++----- src/model/Equity.jl | 8 ++-- src/model/Spline.jl | 10 ++--- src/model/Volatility.jl | 5 +++ src/model/Yield.jl | 8 ++-- src/model/Yield/SmithWilson.jl | 2 +- 27 files changed, 342 insertions(+), 133 deletions(-) create mode 100644 docs/docs/Project.toml create mode 100644 docs/src/API/Bond.md create mode 100644 docs/src/API/Equity.md create mode 100644 docs/src/API/FinanceCore.md create mode 100644 docs/src/API/FinanceModels.md create mode 100644 docs/src/API/Fit.md create mode 100644 docs/src/API/Option.md create mode 100644 docs/src/API/Spline.md create mode 100644 docs/src/API/Volatility.md create mode 100644 docs/src/API/Yield.md create mode 100644 docs/src/Rates.md delete mode 100644 docs/src/api.md rename docs/src/{guide.md => introduction.md} (99%) diff --git a/docs/Project.toml b/docs/Project.toml index 023751fa..004f2732 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,3 +1,4 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +FinanceCore = "b9b1ffdd-6612-4b69-8227-7663be06e089" FinanceModels = "77f2ae65-bdde-421f-ae9d-22f1af19dd76" diff --git a/docs/docs/Project.toml b/docs/docs/Project.toml new file mode 100644 index 00000000..004f2732 --- /dev/null +++ b/docs/docs/Project.toml @@ -0,0 +1,4 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +FinanceCore = "b9b1ffdd-6612-4b69-8227-7663be06e089" +FinanceModels = "77f2ae65-bdde-421f-ae9d-22f1af19dd76" diff --git a/docs/make.jl b/docs/make.jl index d7dc8547..d0d202c9 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -2,9 +2,9 @@ using FinanceModels using Documenter makedocs(; - modules=[FinanceModels], + modules=[FinanceModels, FinanceCore], authors="Alec Loudenback and contributors", - repo="https://github.com/JuliaActuary/FinanceModels.jl/blob/{commit}{path}#L{line}", + repo=Remotes.GitHub("JuliaActuary", "FinanceModels.jl"), sitename="FinanceModels.jl", format=Documenter.HTML(; prettyurls=get(ENV, "CI", "false") == "true", @@ -13,11 +13,24 @@ makedocs(; ), pages=[ "Home" => "index.md", - "Guide" => "guide.md", - "Contracts" => "contracts.md", - "Models, Valuation, and Fitting" => "models.md", - "API Reference" => "api.md", - "Migration Guide" => "migration.md", + "Guide" => [ + "Introduction" => "introduction.md", + "Models, Valuation, and Fitting" => "models.md", + "Contracts" => "contracts.md", + "Rates" => "Rates.md", + "Migration Guide" => "migration.md", + ], + "Modules" => [ + "FinanceModels" => "API/FinanceModels.md", + "FinanceCore" => "API/FinanceCore.md", + "Spline" => "API/Spline.md", + "Fit" => "API/Fit.md", + "Yield" => "API/Yield.md", + "Bond" => "API/Bond.md", + "Equity" => "API/Equity.md", + "Option" => "API/Option.md", + "Volatility" => "API/Volatility.md", + ], "FAQs" => "faq.md", ] ) diff --git a/docs/src/API/Bond.md b/docs/src/API/Bond.md new file mode 100644 index 00000000..1b436b2d --- /dev/null +++ b/docs/src/API/Bond.md @@ -0,0 +1,19 @@ +# FinanceModels.Bond API Reference + +```@index +Modules = [FinanceModels.Bond] +``` + +## Exported API +```@autodocs +Modules = [FinanceModels.Bond] +Private = false +``` + +## Unexported API +```@autodocs +Modules = [FinanceModels.Bond] +Public = false +``` + +Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. diff --git a/docs/src/API/Equity.md b/docs/src/API/Equity.md new file mode 100644 index 00000000..cc2765a6 --- /dev/null +++ b/docs/src/API/Equity.md @@ -0,0 +1,19 @@ +# FinanceModels.Equity API Reference + +```@index +Modules = [FinanceModels.Equity] +``` + +## Exported API +```@autodocs +Modules = [FinanceModels.Equity] +Private = false +``` + +## Unexported API +```@autodocs +Modules = [FinanceModels.Equity] +Public = false +``` + +Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. diff --git a/docs/src/API/FinanceCore.md b/docs/src/API/FinanceCore.md new file mode 100644 index 00000000..9d499c09 --- /dev/null +++ b/docs/src/API/FinanceCore.md @@ -0,0 +1,19 @@ +# FinanceCore API Reference + +```@index +Modules = [FinanceCore] +``` + +## Exported API +```@autodocs +Modules = [FinanceCore] +Private = false +``` + +## Unexported API +```@autodocs +Modules = [FinanceCore] +Public = false +``` + +Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. diff --git a/docs/src/API/FinanceModels.md b/docs/src/API/FinanceModels.md new file mode 100644 index 00000000..41fec671 --- /dev/null +++ b/docs/src/API/FinanceModels.md @@ -0,0 +1,19 @@ +# FinanceModels API Reference + +```@index +Modules = [FinanceModels] +``` + +## Exported API +```@autodocs +Modules = [FinanceModels] +Private = false +``` + +## Unexported API +```@autodocs +Modules = [FinanceModels] +Public = false +``` + +Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. diff --git a/docs/src/API/Fit.md b/docs/src/API/Fit.md new file mode 100644 index 00000000..06ddc825 --- /dev/null +++ b/docs/src/API/Fit.md @@ -0,0 +1,19 @@ +# FinanceModels.Fit API Reference + +```@index +Modules = [FinanceModels.Fit] +``` + +## Exported API +```@autodocs +Modules = [FinanceModels.Fit] +Private = false +``` + +## Unexported API +```@autodocs +Modules = [FinanceModels.Fit] +Public = false +``` + +Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. diff --git a/docs/src/API/Option.md b/docs/src/API/Option.md new file mode 100644 index 00000000..0ddc0fa1 --- /dev/null +++ b/docs/src/API/Option.md @@ -0,0 +1,19 @@ +# FinanceModels.Option API Reference + +```@index +Modules = [FinanceModels.Option] +``` + +## Exported API +```@autodocs +Modules = [FinanceModels.Option] +Private = false +``` + +## Unexported API +```@autodocs +Modules = [FinanceModels.Option] +Public = false +``` + +Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. diff --git a/docs/src/API/Spline.md b/docs/src/API/Spline.md new file mode 100644 index 00000000..bdf404e6 --- /dev/null +++ b/docs/src/API/Spline.md @@ -0,0 +1,19 @@ +# FinanceModels.Spline API Reference + +```@index +Modules = [FinanceModels.Spline] +``` + +## Exported API +```@autodocs +Modules = [FinanceModels.Spline] +Private = false +``` + +## Unexported API +```@autodocs +Modules = [FinanceModels.Spline] +Public = false +``` + +Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. diff --git a/docs/src/API/Volatility.md b/docs/src/API/Volatility.md new file mode 100644 index 00000000..564b9870 --- /dev/null +++ b/docs/src/API/Volatility.md @@ -0,0 +1,19 @@ +# FinanceModels.Volatility API Reference + +```@index +Modules = [FinanceModels.Volatility] +``` + +## Exported API +```@autodocs +Modules = [FinanceModels.Volatility] +Private = false +``` + +## Unexported API +```@autodocs +Modules = [FinanceModels.Volatility] +Public = false +``` + +Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. diff --git a/docs/src/API/Yield.md b/docs/src/API/Yield.md new file mode 100644 index 00000000..3fcd7311 --- /dev/null +++ b/docs/src/API/Yield.md @@ -0,0 +1,19 @@ +# FinanceModels.Yield API Reference + +```@index +Modules = [FinanceModels.Yield] +``` + +## Exported API +```@autodocs +Modules = [FinanceModels.Yield] +Private = false +``` + +## Unexported API +```@autodocs +Modules = [FinanceModels.Yield] +Public = false +``` + +Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. diff --git a/docs/src/Rates.md b/docs/src/Rates.md new file mode 100644 index 00000000..373f8aae --- /dev/null +++ b/docs/src/Rates.md @@ -0,0 +1,62 @@ +## Rates + +We should first discuss `Rate`s, which are reexported from [`FinanceCore.jl`](https://github.com/JuliaActuary/FinanceCore.jl) + +Rates are types that wrap scalar values to provide information about how to determine `discount` and `accumulation` factors. These allow for explicit handling of rate compounding conventions which, if not explicit, is often a source of errors in practice. + +There are two `Frequency` types: + +- `Yields.Periodic(m)` for rates that compound `m` times per period (e.g. `m` times per year if working with annual rates). +- `Yields.Continuous()` for continuously compounding rates. + +#### Examples + +```julia +Continuous(0.05) # 5% continuously compounded +Periodic(0.05,2) # 5% compounded twice per period +``` + +These are both subtypes of the parent `Rate` type and are instantiated as: + +```julia +Rate(0.05,Continuous()) # 5% continuously compounded +Rate(0.05,Periodic(2)) # 5% compounded twice per period +``` + +Broadcast over a vector to create `Rates` with the given compounding: + +```julia +Periodic.([0.02,0.03,0.04],2) +Continuous.([0.02,0.03,0.04]) +``` + +Rates can also be constructed by specifying the `CompoundingFrequency` and then passing a scalar rate: + +```julia +Periodic(1)(0.05) +Continuous()(0.05) +``` + +#### Conversion + +Convert rates between different types with `convert`. E.g.: + +```julia +r = Rate(0.01,Periodic(12)) # rate that compounds 12 times per rate period (ie monthly) + +convert(Yields.Periodic(1),r) # convert monthly rate to annual effective +convert(Yields.Continuous(),r) # convert monthly rate to continuous +``` + +To get the scalar value out of the `Rate`, use `FinanceModels.rate(r)`: + +```julia-rel +julia> r = Rate(0.01,Periodic(12)); +julia> rate(r) +0.01 + +``` + +#### Arithmetic + +Adding, subtracting, multiplying, dividing, and comparing rates is supported. diff --git a/docs/src/api.md b/docs/src/api.md deleted file mode 100644 index 09b2feb4..00000000 --- a/docs/src/api.md +++ /dev/null @@ -1,43 +0,0 @@ -# FinanceModels API Reference - -Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package. - -## Rate Types - -When JuliaActuary packages return a rate, they will be of a `Rate` type, such as `Rate(0.05,Periodic(2))` for a 5% rate compounded twice per period. It is recommended to keep rates typed and use them throughout the ecosystem without modifying it. - -For example, if we construct a curve like this: - -```julia -# 2021-03-31 rates from Treasury.gov -rates =[0.01, 0.01, 0.03, 0.05, 0.07, 0.16, 0.35, 0.92, 1.40, 1.74, 2.31, 2.41] ./ 100 -mats = [1/12, 2/12, 3/12, 6/12, 1, 2, 3, 5, 7, 10, 20, 30] - -curve = FinanceModels.CMT(rates,mats) -``` - -Then rates from this curve will be typed. For example: - -```julia -z = zero(c,10) -``` - -Now, `z` will be: `FinanceModels.Rate{Float64, Continuous}(0.01779624378877313, Continuous())` - -This `Rate` has both the rate an the compounding convention embedded in the datatype. - -You can now use that rate throughout the JuliaActuary ecosystem, such as with ActuaryUtilities.jl: - -```julia -using ActuaryUtilities -present_values(z,cashflows) -``` - -If you need to extract the rate for some reason, you can get the rate by calling `FinanceModels.rate(...)`. Using the above example, `FinanceModels.rate(z)` will return `0.01779624378877313`. - -```@index -``` - -```@autodocs -Modules = [FinanceModels] -``` diff --git a/docs/src/contracts.md b/docs/src/contracts.md index 130c1e09..bc0e024c 100644 --- a/docs/src/contracts.md +++ b/docs/src/contracts.md @@ -1,13 +1,5 @@ # Contracts -## Page Contents - -```@contents -Pages = ["contracts.md"] -Depth = 4 -``` - - ## **Contracts** - A composable way to represent financial instruments Contracts are a composable way to represent financial instruments. They are, in essence, anything that is a collection of cashflows. Contracts can be combined to represent more complex instruments. For example, a bond can be represented as a collection of cashflows that correspond to the coupon payments and the principal repayment. @@ -96,26 +88,8 @@ Note that all contracts in FinanceModels.jl are currently *unit* contracts in th #### More complex Contracts -**When the cashflow depends on a model**. An example of this is a floating bond where the coupon paid depends on a view of forward rates. See [this section in the overview](guide.html#Contracts-that-depend-on-the-model-(or-multiple-models)) on projections for how this is handled. - -## Availalbe Contracts & Modules - -### `Bond` Module +**When the cashflow depends on a model**. An example of this is a floating bond where the coupon paid depends on a view of forward rates. See [this section in the overview](@ref Contracts-that-depend-on-the-model-(or-multiple-models)) on projections for how this is handled. -```@autodocs -Modules = [FinanceModels.Bond] -``` - -### Other Contracts - -```@docs -Composite -CommonEquity -Forward -``` - -### Derivatives +## Available Contracts & Modules -```@autodocs -Modules = [FinanceModels.Option] -``` +See the Modules in the left navigation for details on available contracts/models/functions. diff --git a/docs/src/faq.md b/docs/src/faq.md index acd76c12..4eb607d0 100644 --- a/docs/src/faq.md +++ b/docs/src/faq.md @@ -19,10 +19,10 @@ Transducers are a [rich and powerful way to express programs](https://www.youtub - To regular end-users who just use what is given to them here, the transducers internals are effectively completely hidden - To moderately advanced users who want to extend the functionality, as the examples show the only real exposure here is a weird function name ( `__foldl__`) with for loop with a `return` signature that has some extra information. -A number of examples of extending the package are given on the [Guide](./guide.html) page and the of course the source code itself offers examples of existing `Projection`s and `Contract`s. +A number of examples of extending the package are given on the [FinanceModels.jl Guide](@ref) page and the of course the source code itself offers examples of existing `Projection`s and `Contract`s. ## I have another question -Ask on the discussion forum here: https://github.com/JuliaActuary/Yields.jl/discussions +Ask on the discussion forum here: [https://github.com/JuliaActuary/FinanceModels.jl/discussions](https://github.com/JuliaActuary/FinanceModels.jl/discussions) diff --git a/docs/src/index.md b/docs/src/index.md index c03fde2e..97eb3d08 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -43,7 +43,7 @@ present_value(m_rate,Cashflow(10,3)) # 9.15... ## Overview of FinanceModels -![A conceptual sketch of FinanceModels.jl](/docs/src/assets/relations.png) +![A conceptual sketch of FinanceModels.jl](assets/relations.png) Often we start with observed or assumed values for existing contracts. We want to then use those assumed values to extend the valuation logic to new contracts. For example, we may have a set of bond yields which we then want to discount a series of insurance obligations. diff --git a/docs/src/guide.md b/docs/src/introduction.md similarity index 99% rename from docs/src/guide.md rename to docs/src/introduction.md index cd7dde91..8c3dc046 100644 --- a/docs/src/guide.md +++ b/docs/src/introduction.md @@ -2,7 +2,7 @@ **FinanceModels.jl** provides a set of composable contracts, models, and functions that allow for modeling of both simple and complex financial instruments. The resulting models, such as discount rates or term structures, can then be used across the JuliaActuary ecosystem to perform actuarial and financial analysis. -![A conceptual sketch of FinanceModels.jl](./assets/relations.png) +![A conceptual sketch of FinanceModels.jl](assets/relations.png) ## 1. `Cashflow` - a fundamental financial type @@ -332,7 +332,7 @@ julia> p = Projection( ``` And then collect the values: -[](url) + ```julia-repl julia> collect(p) 10-element Vector{NamedTuple{(:time, :payment, :outstanding), Tuple{Float64, Float64, Float64}}}: diff --git a/docs/src/migration.md b/docs/src/migration.md index c2f5a329..6636522d 100644 --- a/docs/src/migration.md +++ b/docs/src/migration.md @@ -37,7 +37,7 @@ quotes = ParYield.(rates,timepoints) model = fit(SmithWilson(),quotes) ``` -#### Discussion +#### Details of changes Previously the kind of contract, the implied quotes, the type of model, and how the fitting process worked were all combined into a single call (`Yields.Par`). This minimized the amount of code needed to construct a yield curve, but left it fairly cumbersome to extend the package. For example, for every new yield curve model, methods for `Par`, `CMT`, `OIS`, `Zero`, ... had to be defined. Additionally, all of the inputs needed to be yields - specifying a price was not available as an argument to fit. diff --git a/docs/src/models.md b/docs/src/models.md index ba5c7e65..d42fe29b 100644 --- a/docs/src/models.md +++ b/docs/src/models.md @@ -1,12 +1,5 @@ # Models, Valuation, Projections, and Fitting -## Page Contents - -```@contents -Pages = ["models.md"] -Depth = 4 -``` - ## Introduction Conceptually, we have an iterative process: @@ -61,24 +54,33 @@ Continuous()(0.05) Convert rates between different types with `convert`. E.g.: -```julia-repl -r = Rate(Yields.Periodic(12),0.01) # rate that compounds 12 times per rate period (ie monthly) +```julia +r = Rate(0.01,Periodic(12)) # rate that compounds 12 times per rate period (ie monthly) convert(Yields.Periodic(1),r) # convert monthly rate to annual effective convert(Yields.Continuous(),r) # convert monthly rate to continuous ``` +To get the scalar value out of the `Rate`, use `FinanceModels.rate(r)`: + +```julia-rel +julia> r = Rate(0.01,Periodic(12)); +julia> rate(r) +0.01 + +``` + #### Arithmetic Adding, subtracting, multiplying, dividing, and comparing rates is supported. ### Available Models - Yields -- [`Yield.Constant`](@ref) -- Bootstrapped [`Spline`](@ref) -- [`Yield.SmithWilson`](@ref) -- [`Yield.NelsonSiegel`](@ref) -- [`Yield.NelsonSiegelSvensson`](@ref) +- [`FinanceModels.Yield.Constant`](@ref) +- Bootstrapped [`Spline`](@ref FinanceModels.Spline)s +- [`FinanceModels.Yield.SmithWilson`](@ref) +- [`FinanceModels.Yield.NelsonSiegel`](@ref) +- [`FinanceModels.Yield.NelsonSiegelSvensson`](@ref) Yield models can also be composed. Here is an example of fitting rates and spread separately and then adding the two models together: @@ -106,20 +108,20 @@ julia> discount(0.04,3) ### Creating New Yield Models -See the [Guide](guide.html) for an example of creating a model from scratch. Some additional aspects to note: +See the [FinanceModels.jl Guide](@ref) for an example of creating a model from scratch. Some additional aspects to note: -- The only method that must be defined to calculate the [`present_value`](@ref) of something is [`discount`](@ref). Other methods will be inferred. -- Other methods that are imputed by default, but can be extended include: [`accumulation`](@ref), [`forward`](@ref), [`par`](@ref), [`zero`](@ref), and [`rate`](@ref). +- The only method that must be defined to calculate the [`FinanceCore.present_value`](@ref) of something is [`FinanceCore.discount`](@ref). Other methods will be inferred. +- Other methods that are imputed by default, but can be extended include: [`FinanceCore.accumulation`](@ref), [`FinanceModels.forward`](@ref), [`FinanceModels.par`](@ref), [`FinanceModels.zero`](@ref), and [`FinanceModels.rate`](@ref). ## Equity and Volatility Models ### Available Models - Option Valuation -- [`Option.BlackScholesMerton`](@ref) +- [`FinanceModels.Equity.BlackScholesMerton`](@ref) ### Available Models - Volatility -- [`Volatility.Constant`](@ref) +- [`FinanceModels.Volatility.Constant`](@ref) #### Creating new Volatility Models diff --git a/src/Contract.jl b/src/Contract.jl index 17ea00ed..9ed3a1ac 100644 --- a/src/Contract.jl +++ b/src/Contract.jl @@ -92,7 +92,7 @@ Note that there are a number of convienience constructors which return a Quote f - [`CMTYield`](@ref) - [`OISYield`](@ref) -See also [`Quote`](@ref). +See also [`FinanceCore.Quote`](@ref). # Examples @@ -131,7 +131,7 @@ end An object representing a floating coupon bond. (`coupon_rate` + reference rate) / `frequency` is the actual payment amount, 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. -See also [`Quote`](@ref). +See also [`FinanceCore.Quote`](@ref). # Examples @@ -206,7 +206,7 @@ Returns a `Quote` for the correpsonding bond implied by the given bond equivalen Use broadcasting to create a set of quotes given a collection of FinanceModels and maturities, e.g. `CMTYield.(FinanceModels,maturities)`. -See also [`Quote`](@ref), [`Bond.Fixed`](@ref) +See also [`FinanceCore.Quote`](@ref), [`Bond.Fixed`](@ref) # Examples @@ -235,7 +235,7 @@ Returns the implied `Quote` for the fixed bond implied by the given `yield` and Use broadcasting to create a set of quotes given a collection of FinanceModels and maturities, e.g. `OISYield.(FinanceModels,maturities)`. -See also [`Quote`](@ref), [`Bond.Fixed`](@ref) +See also [`FinanceCore.Quote`](@ref), [`Bond.Fixed`](@ref) # Examples @@ -342,6 +342,26 @@ struct CommonEquity <: FinanceCore.AbstractContract end module Option import ..FinanceCore: AbstractContract, Timepoint + +""" + EuroCall(contract,strike,maturity) + +A European call option on the given contract with the given strike and maturity. + +# Arguments + - contract::AbstractContract - The underlying contract. + - strike::Real - The strike price. + - maturity::Union{Real,Date} - The maturity of the option. + + Supertype Hierarchy +≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ + + EuroCall{S,K,M} <: FinanceCore.AbstractContract <: Any + + + + +""" struct EuroCall{S<:AbstractContract,K<:Real,M<:Timepoint} <: AbstractContract underlying::S strike::K diff --git a/src/fit.jl b/src/fit.jl index 66023708..b80e07f6 100644 --- a/src/fit.jl +++ b/src/fit.jl @@ -48,7 +48,7 @@ end """ Bootstrap() -A singleton type which is passed to `fit` in order to bootstrap [`Spline`](@ref)s. The curves are fit such that the spline passes through the zero rates of the curve. +A singleton type which is passed to `fit` in order to bootstrap Splines. The curves are fit such that the spline passes through the zero rates of the curve. A subtype of FitMethod. @@ -153,24 +153,24 @@ __default_optim(m) = ECA() """ fit( - mod0, + model, quotes, method=Fit.Loss(x -> x^2); - variables=__default_optic(mod0), - optimizer=__default_optim(mod0) + variables=__default_optic(model), + optimizer=__default_optim(model) ) Fit a model to a collection of quotes using a loss function and optimization method. ## Arguments -- `mod0`: The initial model to fit, which is generally an instantiated but un-optimized model. +- `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, `mod0` should be a spline such as `Spline.Linear()`, `Spline.Cubic()`... -- `variables=__default_optic(mod0)`: The variables to optimize over. This is an optic specifying which parameters of the modle can vary. See extended help for more. -- `optimizer=__default_optim(mod0)`: The optimization algorithm to use. The default optimization for a given model is ECA from Metahueristics.jl; see extended help for more on customizing the solver including setting the seed. + - `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 an optic specifying which parameters of the modle can vary. See extended help for more. +- `optimizer=__default_optim(model)`: The optimization algorithm to use. The default optimization for a given model is ECA from Metahueristics.jl; see extended help for more on customizing the solver including setting the seed. -The optimization routine will then attempt to modify parameters of `mod0` 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(...)`. +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 `EuroCall`s with a `Yield.Constant`, you will get an error because the `present_value(m<:Yield.Constant,o<:EuroCall)` is not defined. @@ -179,11 +179,11 @@ Different types of quotes are appropriate for different kinds of models. For exa # Examples ```julia -julia> mod0 = Yield.Constant(); +julia> model = Yield.Constant(); julia> quotes = ZCBPrice([0.9, 0.8, 0.7,0.6]); -julia> fit(mod0,quotes) +julia> fit(model,quotes) ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀Yield Curve (FinanceModels.Yield.Constant)⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ┌────────────────────────────────────────────────────────────┐ diff --git a/src/model/Equity.jl b/src/model/Equity.jl index e5491525..736e2f68 100644 --- a/src/model/Equity.jl +++ b/src/model/Equity.jl @@ -1,7 +1,7 @@ """ The `Equity` module provides equity-related model definitions. -See also: the [`Volatility`](@ref) module. +See also: the [`Volatility`](@ref FinanceModels.Volatility-API-Reference) module. """ module Equity import ..AbstractModel @@ -16,14 +16,14 @@ A struct representing the Black-Scholes-Merton model for equity prices. # Arguments - `r`: The risk-free rate. - `q`: The dividend yield. -- `σ`: The volatility model of the underlying asset (see [`Volatility`](@ref) module) +- `σ`: The volatility model of the underlying asset (see [`Volatility`](@ref FinanceModels.Volatility-API-Reference) module) # Fields - `r`: The risk-free rate. - `q`: The dividend yield. -- `σ`: The volatility model of the underlying asset (see [`Volatility`](@ref) module) +- `σ`: The volatility model of the underlying asset (see [`Volatility`](@ref FinanceModels.Volatility-API-Reference) module) -When [`fit`](@ref), the volatility will be solved-for; volatility itself is a sub-model that will be optimized with a default optimization bound of `0.0 .. 10.0` +When [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss)ting, the volatility will be solved-for; volatility itself is a sub-model that will be optimized with a default optimization bound of `0.0 .. 10.0` # Examples ```julia-repl diff --git a/src/model/Spline.jl b/src/model/Spline.jl index e3004c8f..7e1b9638 100644 --- a/src/model/Spline.jl +++ b/src/model/Spline.jl @@ -1,11 +1,11 @@ """ -Spline is a module which offers various degree splines used for fitting or bootstraping curves via the [`fit`](@ref) function. +Spline is a module which offers various degree splines used for fitting or bootstraping curves via the [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss) function. Available methods: - `Spline.BSpline(n)` where n is the nth order. A spline function of order n is a piecewise polynomial function of degree n − 1. This means that, e.g., cubic polynomial is a fourth degree B-Spline. -This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref). +This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss). and convienience methods which create a `Spline.BSpline` object of the appropriate order. @@ -26,7 +26,7 @@ end """ Spline.Linear() -Create a linear B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref). +Create a linear B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss). # Returns - A `BSpline` object representing a linear B-spline. @@ -44,7 +44,7 @@ Linear() = BSpline(2) """ Spline.Quadratic() -Create a quadratic B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref). +Create a quadratic B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss). # Returns - A `BSpline` object representing a quadratic B-spline. @@ -60,7 +60,7 @@ Quadratic() = BSpline(3) """ Spline.Cubic() -Create a cubic B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref). +Create a cubic B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss). # Returns - A `BSpline` object representing a cubic B-spline. diff --git a/src/model/Volatility.jl b/src/model/Volatility.jl index 784e4472..3396a637 100644 --- a/src/model/Volatility.jl +++ b/src/model/Volatility.jl @@ -4,6 +4,11 @@ import ..AbstractModel abstract type AbstractVolatilityModel <: AbstractModel end +""" + Volatility.Constant(σ) + +A constant volatility per period. If σ is not explicitly passed, then it is set to zero. +""" struct Constant{T} <: AbstractVolatilityModel σ::T end diff --git a/src/model/Yield.jl b/src/model/Yield.jl index 0edfdbdf..3370dd1b 100644 --- a/src/model/Yield.jl +++ b/src/model/Yield.jl @@ -1,4 +1,3 @@ - module Yield import ..AbstractModel import ..FinanceCore @@ -16,9 +15,10 @@ abstract type AbstractYieldModel <: AbstractModel end """ Constant(rate) -A yield curve representing a flat term structure. +A yield curve representing a flat term structure. `rate` can be a [`Rate`](@ref) object or a `Real` object. + -The solver will attempt to fit a discount rate with the range of: `-1.0 .. 1.0` +If [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss)ing with the default FinanceModels.jl settings, the solver will attempt to fit a discount rate with the range of: `-1.0 .. 1.0` """ struct Constant{R} <: AbstractYieldModel rate::R @@ -200,7 +200,7 @@ julia> FinanceCore.discount(fwd,1) # `curve` has effectively been reindexed to ` While `ForwardStarting` could be nested so that, e.g. the third period's curve is the one-period forward of the second period's curve, it will be more efficient to reuse the initial curve from a runtime and compiler perspective. -`ForwardStarting` is not used to construct a curve based on forward rates. See [`Forward`](@ref) instead. +`ForwardStarting` is not used to construct a curve based on forward rates. """ struct ForwardStarting{T,U} <: AbstractYieldModel curve::U diff --git a/src/model/Yield/SmithWilson.jl b/src/model/Yield/SmithWilson.jl index 5d9fa1b5..f451a988 100644 --- a/src/model/Yield/SmithWilson.jl +++ b/src/model/Yield/SmithWilson.jl @@ -12,7 +12,7 @@ using ..FinanceCore Create a yield curve object that implements the Smith-Wilson interpolation/extrapolation scheme. -To calibrate a curve, you generally want to construct the object without the `u` and `qb` arguments and call [`fit`](@ref) in conjunction with Quotes (`fit` requires no third parameter for SmithWilson curves). See **Examples** for what this looks like. +To calibrate a curve, you generally want to construct the object without the `u` and `qb` arguments and call [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss) in conjunction with Quotes (`fit` requires no third parameter for SmithWilson curves). See **Examples** for what this looks like. Positional arguments to construct a curve: - A curve can be with `u` is the timepoints coming from the calibration, and `qb` is the internal parameterization of the curve that ensures that the calibration is correct. Users may prefer the other constructors but this mathematical constructor is also available.