bristlecone


Bristlecone

Bristlecone is a library for conducting model-fitting and model-selection analyses on time-series data. Although originally designed for the investigation of non-linear dynamics within ecological and environmental sciences, the library can be used across finance, econometrics and other fields that apply non-linear modelling techniques.

Quick Start

Once you have installed the .NET SDK, the Bristlecone library can be installed from NuGet.

Use in an F# script

img/example.png

Example

This example demonstrates the layout of a model when defined in Bristlecone.

open Bristlecone            // Opens Bristlecone core library and estimation engine
open Bristlecone.Language   // Open the language for writing Bristlecone models

let hypothesis =

    let vonBertalanffy = 
        Parameter "η" * This ** Parameter "β" - Parameter "κ" * This

    Model.empty
    |> Model.addEquation       "mass"   vonBertalanffy
    |> Model.estimateParameter "η"      noConstraints 0.50 1.50 
    |> Model.estimateParameter "β"      noConstraints 0.01 1.00
    |> Model.estimateParameter "κ"      noConstraints 0.01 1.00 
    |> Model.useLikelihoodFunction (ModelLibrary.Likelihood.sumOfSquares [ "mass" ])
    |> Model.compile

let engine = 
    Bristlecone.mkContinuous
    |> Bristlecone.withTunedMCMC [ ]//Optimisation.MonteCarlo.TuneMethod.CovarianceWithScale 0.750, 200, Optimisation.EndConditions.afterIteration 25000  ]

let testSettings = Bristlecone.Test.TestSettings<float>.Default
Bristlecone.testModel engine testSettings hypothesis

In the above snippet, a von Bertalanffy growth model is defined as a hypothesis to test. We then create an EstimationEngine, which defines the methodology for model-fitting. In Bristlecone, an EstimationEngine is created and customised using the F# forward pipe operator (for R users this may be familiar; this concept was adapted into the dplyr %>% operator). The call to testModel generates random test data, and assesses whether the model-fitting method can accurately estimate known parameters.

Samples & documentation

The API reference is automatically generated from Markdown comments in the library implementation.

Contributing and copyright

The project is hosted on GitHub where you can report issues, fork the project and submit pull requests. If you're adding a new public API, please also consider adding samples that can be turned into a documentation. You might also want to read the library design notes to understand how it works.

The library is available under an MIT license, which allows modification and redistribution for both commercial and non-commercial purposes. For more information see the License file in the GitHub repository.

namespace Bristlecone
Multiple items
module Bristlecone from Bristlecone

--------------------
namespace Bristlecone
module Language from Bristlecone
<summary> An F# Domain Specific Language (DSL) for scripting with Bristlecone. </summary>
val hypothesis : ModelSystem.ModelSystem
val vonBertalanffy : ModelExpression
Multiple items
union case ModelExpression.Parameter: string -> ModelExpression

--------------------
module Parameter from Bristlecone
union case ModelExpression.This: ModelExpression
module Model from Bristlecone.Language
<summary> Terms for scaffolding a model system for use with Bristlecone. </summary>
val empty : ModelBuilder.ModelBuilder
val addEquation : name:string -> eq:ModelExpression -> builder:ModelBuilder.ModelBuilder -> ModelBuilder.ModelBuilder
val estimateParameter : name:string -> constraintMode:Parameter.Constraint -> lower:float -> upper:float -> builder:ModelBuilder.ModelBuilder -> ModelBuilder.ModelBuilder
val noConstraints : Parameter.Constraint
val useLikelihoodFunction : likelihoodFn:ModelSystem.Likelihood -> builder:ModelBuilder.ModelBuilder -> ModelBuilder.ModelBuilder
module ModelLibrary
<summary> Pre-built model parts for use in Bristlecone. </summary>
module Likelihood from ModelLibrary
<summary> Likelihood functions to represent a variety of distributions and data types. </summary>
val sumOfSquares : keys:string list -> 'a -> data:CodedMap<ModelSystem.PredictedSeries> -> float
val compile : (ModelBuilder.ModelBuilder -> ModelSystem.ModelSystem)
val engine : EstimationEngine.EstimationEngine<float,float>
val mkContinuous : EstimationEngine.EstimationEngine<float,float>
<summary> A standard `EstimationEngine` for ordinary differential equation models. </summary>
val withTunedMCMC : tuning:seq<Optimisation.MonteCarlo.TuneStep<float>> -> engine:EstimationEngine.EstimationEngine<float,'a> -> EstimationEngine.EstimationEngine<float,'a>
val testSettings : Bristlecone.Test.TestSettings<float>
module Test from Bristlecone.Bristlecone
type TestSettings<'a> = { TimeSeriesLength: int StartValues: CodedMap<'a> EndCondition: EndCondition<'a> GenerationRules: GenerationRule list NoiseGeneration: Pool -> CodedMap<TimeSeries<'a>> -> CodedMap<TimeSeries<'a>> EnvironmentalData: CodedMap<TimeSeries<'a>> Resolution: FixedTemporalResolution Random: Random StartDate: DateTime Attempts: int } static member Default : TestSettings<float>
Multiple items
val float : value:'T -> float (requires member op_Explicit)
<summary>Converts the argument to 64-bit float. This is a direct conversion for all primitive numeric types. For strings, the input is converted using <c>Double.Parse()</c> with InvariantCulture settings. Otherwise the operation requires an appropriate static conversion method on the input type.</summary>
<param name="value">The input value.</param>
<returns>The converted float</returns>


--------------------
[<Struct>] type float = System.Double
<summary>An abbreviation for the CLI type <see cref="T:System.Double" />.</summary>
<category>Basic Types</category>


--------------------
type float<'Measure> = float
<summary>The type of double-precision floating point numbers, annotated with a unit of measure. The unit of measure is erased in compiled code and when values of this type are analyzed using reflection. The type is representationally equivalent to <see cref="T:System.Double" />.</summary>
<category index="6">Basic Types with Units of Measure</category>
val testModel : engine:EstimationEngine.EstimationEngine<float,float> -> settings:Bristlecone.Test.TestSettings<float> -> model:ModelSystem.ModelSystem -> Result<Bristlecone.Test.TestResult,string>
<summary> **Description** Test that the specified estimation engine can correctly estimate known parameters. Random parameter sets are generated from the given model system. **Parameters** * `model` - a `ModelSystem` of equations and parameters * `testSettings` - settings * `engine` - an `EstimationEngine` </summary>