Bristlecone

Bristlecone is a library for easily composing theoretical models into larger systems, and subsequently 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

Bristlecone is an F# .NET library. You can easily get started by installing the latest .NET SDK. You may then simply use the Bristlecone package in a script, application, or library. The nuget package is available here.

To use in an F# script

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 mass = state<1> "mass"

let hypothesis =

    // Model parameters:
    let η = parameter "η" NoConstraints 0.50 1.50
    let β = parameter "β" NoConstraints 0.01 1.00 // m
    let κ = parameter "κ" NoConstraints 0.01 1.00

    // Likelihood parameters:
    let sigma = parameter "σ[x]" Positive 0.01 0.10

    let vonBertalanffy = P η * This ** P β - P κ * This

    let NLL = ModelLibrary.NegLogLikelihood.Normal (Require.state mass) sigma

    Model.empty
    |> Model.addRateEquation mass vonBertalanffy
    |> Model.estimateParameter η
    |> Model.estimateParameter β
    |> Model.estimateParameter κ
    |> Model.useLikelihoodFunction NLL
    |> Model.compile

// Given some data (loaded using Bristlecone functions, FSharp.Data, etc.)...
fun data ->
  let engine = Bristlecone.mkContinuous ()
  let endCond = Optimisation.EndConditions.atIteration 10000<iteration>
  Bristlecone.fit engine endCond data hypothesis

In the above snippet, a von Bertalanffy growth model is defined as a model hypothesis. 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).

To apply the model to data, the Bristlecone.fit function can be called with an end condition for the optimisation routine chosen in the given engine.

Samples & documentation

An API reference is automatically generated from XML comments in the library implementation.

In addition, this documentation includes step-by-step example analyses. Each analysis may be downloaded as an F# script or Jupyter notebook using the buttons at the top of each example page.

• For basic functions, a comparison of plant growth models and a classic predator-prey example cover model-fitting with Bristlecone.

• For dendroecology, a shrub-resource example demonstrates model-fitting and model-selection (MFMS) with Bristlecone.

• For palaeoecology, a sediment core example shows similar methods applied to sedimentary isotope and pollen time-series with uneven time-steps.

• The 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.

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 documentation (using fsdocs literal scripting).

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.