New Documentation Structure

.github/workflows/CompatHelper.yml

@@ -30,7 +30,7 @@ jobs:
           #         push!(subdirs, d)
           #     end
           # end
-          subdirs = ["", "tutorials/00-introduction", "tutorials/01-gaussian-mixture-model", "tutorials/04-hidden-markov-model", "tutorials/08-multinomial-logistic-regression", "tutorials/10-bayesian-differential-equations", "tutorials/11-probabilistic-pca", "tutorials/12-gaussian-process", "tutorials/13-seasonal-time-series", "tutorials/14-minituring"]
+          subdirs = ["", "tutorials/00-introduction", "tutorials/01-gaussian-mixture-model", "tutorials/04-hidden-markov-model", "tutorials/08-multinomial-logistic-regression", "tutorials/10-bayesian-differential-equations", "tutorials/11-probabilistic-pca", "tutorials/12-gaussian-process", "tutorials/13-seasonal-time-series", "tutorials/14-minituring", "tutorials/docs-00-getting-started"]
           CompatHelper.main(; subdirs)
         shell: julia --color=yes {0}
         env:

.gitignore

@@ -13,3 +13,4 @@ Testing/
 /*/*/jl_*/
 /Manifest.toml
 /test/Manifest.toml
+.vscode

src/TuringTutorials.jl

@@ -10,6 +10,7 @@ using Pkg: Pkg
 const REPO_DIR = dirname(@__DIR__)
 const CSS_FILE = joinpath(REPO_DIR, "templates", "skeleton_css.css")
 const LATEX_FILE = joinpath(REPO_DIR, "templates", "julia_tex.tpl")
+const WEAVE_DIRECTORY = "tutorials"
 
 const DEFAULT_BUILD = (:script, :html, :github)
 
@@ -33,15 +34,15 @@ function weave(
         )
     end
 
-    target = joinpath(REPO_DIR, "tutorials", folder, file)
+    target = joinpath(REPO_DIR, WEAVE_DIRECTORY, folder, file)
     @info("Weaving $(target)")
 
     # Activate project
     # TODO: use separate Julia process?
-    if isfile(joinpath(REPO_DIR, "tutorials", folder, "Project.toml")) &&
+    if isfile(joinpath(REPO_DIR, WEAVE_DIRECTORY, folder, "Project.toml")) &&
         (:github in build || :html in build || :pdf in build)
         @info("Instantiating", folder)
-        Pkg.activate(joinpath(REPO_DIR, "tutorials", folder))
+        Pkg.activate(joinpath(REPO_DIR, WEAVE_DIRECTORY, folder))
         Pkg.instantiate()
         Pkg.build()
 
@@ -92,14 +93,14 @@ end
 
 # Weave all tutorials
 function weave(; kwargs...)
-    for folder in readdir(joinpath(REPO_DIR, "tutorials"))
+    for folder in readdir(joinpath(REPO_DIR, WEAVE_DIRECTORY))
         weave(folder; kwargs...)
     end
 end
 
 # Weave a folder of tutorials
 function weave(folder::AbstractString; kwargs...)
-    for file in readdir(joinpath(REPO_DIR, "tutorials", folder))
+    for file in readdir(joinpath(REPO_DIR, WEAVE_DIRECTORY, folder))
         # Skip non-`.jmd` files
         endswith(file, ".jmd") || continue
 

tutorials/docs-00-getting-started/00_getting-started.jmd

@@ -0,0 +1,110 @@
+---
+title: Getting Started
+permalink: /docs/using-turing/get-started
+redirect_from: docs/0-gettingstarted/
+weave_options:
+  error : false
+---
+
+# Getting Started
+
+## Installation
+
+To use Turing, you need to install Julia first and then install Turing.
+
+### Install Julia
+
+You will need to install Julia 1.3 or greater, which you can get from [the official Julia website](http://julialang.org/downloads/).
+
+### Install Turing.jl
+
+Turing is an officially registered Julia package, so you can install a stable version of Turing by running the following in the Julia REPL:
+
+```julia
+using Pkg
+Pkg.add("Turing")
+```
+
+You can check if all tests pass by running `Pkg.test("Turing")` (it might take a long time)
+
+## Example
+
+Here's a simple example showing Turing in action.
+
+First, we can load the Turing and StatsPlots modules
+
+```julia
+using Turing
+using StatsPlots
+```
+
+Then, we define a simple Normal model with unknown mean and variance
+
+```julia
+@model function gdemo(x, y)
+    s² ~ InverseGamma(2, 3)
+    m ~ Normal(0, sqrt(s²))
+    x ~ Normal(m, sqrt(s²))
+    return y ~ Normal(m, sqrt(s²))
+end
+```
+
+Then we can run a sampler to collect results. In this case, it is a Hamiltonian Monte Carlo sampler
+
+```julia
+chn = sample(gdemo(1.5, 2), HMC(0.1, 5), 1000)
+```
+
+We can plot the results
+
+```julia
+plot(chn)
+```
+
+In this case, because we use the [normal-inverse gamma distribution](https://en.wikipedia.org/wiki/Normal-inverse-gamma_distribution)
+as a [conjugate prior](https://en.wikipedia.org/wiki/Conjugate_prior), we can compute
+its updated mean as follows:
+
+```julia
+s² = InverseGamma(2, 3)
+m = Normal(0, 1)
+data = [1.5, 2]
+x_bar = mean(data)
+N = length(data)
+
+mean_exp = (m.σ * m.μ + N * x_bar) / (m.σ + N)
+```
+
+We can also compute the updated variance
+
+```julia
+updated_alpha = shape(s²) + (N / 2)
+updated_beta =
+    scale(s²) +
+    (1 / 2) * sum((data[n] - x_bar)^2 for n in 1:N) +
+    (N * m.σ) / (N + m.σ) * ((x_bar)^2) / 2
+variance_exp = updated_beta / (updated_alpha - 1)
+```
+
+Finally, we can check if these expectations align with our HMC approximations
+from earlier. We can compute samples from a normal-inverse gamma following the
+equations given [here](https://en.wikipedia.org/wiki/Normal-inverse-gamma_distribution#Generating_normal-inverse-gamma_random_variates).
+
+```julia
+function sample_posterior(alpha, beta, mean, lambda, iterations)
+    samples = []
+    for i in 1:iterations
+        sample_variance = rand(InverseGamma(alpha, beta), 1)
+        sample_x = rand(Normal(mean, sqrt(sample_variance[1]) / lambda), 1)
+        sanples = append!(samples, sample_x)
+    end
+    return samples
+end
+
+samples = sample_posterior(updated_alpha, updated_beta, mean_exp, 2, 1000);
+```
+
+```julia
+density(analytical_samples; label="Posterior (Analytical)")
+density!(chn[:m]; label="Posterior (HMC)")
+```