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.
Once you have installed the .NET SDK, the Bristlecone library
can be installed from NuGet.
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.
The API reference is automatically generated from Markdown comments in the library implementation.
Tutorial covers the basic components and workflow of Bristlecone.
-
API Reference contains automatically generated documentation for all types, modules
and functions in the library. This includes additional brief samples on using most of the
functions.
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>