Missing documentation for autocorrelation

[bvenn]

Description

Autocorrelation describes the correlation of data with itself but shifted. It helps identifying randomness or time dependent patterns. The autocorrelation in Correlation module lacks in proper documentation and should be verified.

The example in https://www.itl.nist.gov/div898/handbook/eda/section3/eda35c.htm cannot be reproduced with the current implementation.

To get a visual impression what the implemented autocorrelation function does, run the following. It shows a gaussian distribution that is shifted with different lags.

#r "nuget: FSharp.Stats, 0.5.0"
#r "nuget: Plotly.NET"

open FSharp.Stats
open Plotly.NET

let x = [0. .. 100.]
let gaussPDF = Distributions.Continuous.Normal.PDF (10.) 2.
let yGauss = x |> List.map (gaussPDF) |> vector

let plotCorr lag =
    let v1' = yGauss.[0..(yGauss.Length-1 - lag)]
    let v2' = yGauss.[lag..] 
    [
        [
            Chart.Point(v1'|> Seq.indexed,Name="v1")
            Chart.Point(v2'|> Seq.indexed,Name="v2")
        ] 
        |> Chart.combine
        |> Chart.withXAxisStyle "x values" 
        |> Chart.withYAxisStyle "y values"
        
        Chart.Point(v1',v2',Name="correlation") |> Chart.withXAxisStyle "v1 values" |> Chart.withYAxisStyle "v2 values"
    ]
    |> Chart.Grid(2,1)
    |> Chart.withTitle (sprintf "pearsons r: %.2f" (Correlation.Seq.pearson v1' v2'))
    |> Chart.withTemplate ChartTemplates.lightMirrored
    |> Chart.show

plotCorr 0 
plotCorr 1 
plotCorr 80

Pointers

• Check out the current documentation.
• Extend the description of the documentation
• use cases of autocorrelation
• special cases
• more examples
• Should negative lags be a valid input? If yes, is it possible or has this functionality to be added?
• Of course you can start writing in e.g. markdown/this issue and afterwards we try to incorporate into the library.

References

Hints (click to expand if you need additional pointers)

• To be able to contribute to this library you'll need
  • an GitHub account
  • an IDE like Visual Studio Community or Visual Studio Code
  • dotnet 6 sdk
• to build the binaries yourself follow the instructions
• while working on the FSharp.Stats documentation (any file within https://github.com/fslaborg/FSharp.Stats/tree/developer/docs) you can navigate to the project folder with a prompt of your choice and use the command ./build watchdocs
• unit tests can be executed via ./build runtests