You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Remove quick start -- it's repeated content
* Restructure documentation
* Streamline introductory tutorial
The excised material is more appropriate for the very first page that
people click on.
* Streamline 'Getting Started' page
1. Remove the section on posterior checks; this is the landing page and
it's not necessary for people reading about the library for the first
time to go through that.
2. Signpost the way to the rest of the documentation at the bottom.
3. Minor wording changes
* Update _quarto.yml
Co-authored-by: Hong Ge <[email protected]>
---------
Co-authored-by: Hong Ge <[email protected]>
Copy file name to clipboardExpand all lines: tutorials/00-introduction/index.qmd
+15-20
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
title: Introduction to Turing
2
+
title: "Introduction: Coin Flipping"
3
3
engine: julia
4
4
aliases:
5
5
- ../
@@ -12,23 +12,12 @@ using Pkg;
12
12
Pkg.instantiate();
13
13
```
14
14
15
-
### Introduction
15
+
This is the first of a series of guided tutorials on the Turing language.
16
+
In this tutorial, we will use Bayesian inference to estimate the probability that a coin flip will result in heads, given a series of observations.
16
17
17
-
This is the first of a series of tutorials on the universal probabilistic programming language **Turing**.
18
+
### Setup
18
19
19
-
Turing is a probabilistic programming system written entirely in Julia. It has an intuitive modelling syntax and supports a wide range of sampling-based inference algorithms.
20
-
21
-
Familiarity with Julia is assumed throughout this tutorial. If you are new to Julia, [Learning Julia](https://julialang.org/learning/) is a good starting point.
22
-
23
-
For users new to Bayesian machine learning, please consider more thorough introductions to the field such as [Pattern Recognition and Machine Learning](https://www.springer.com/us/book/9780387310732). This tutorial tries to provide an intuition for Bayesian inference and gives a simple example on how to use Turing. Note that this is not a comprehensive introduction to Bayesian machine learning.
24
-
25
-
### Coin Flipping Without Turing
26
-
27
-
The following example illustrates the effect of updating our beliefs with every piece of new evidence we observe.
28
-
29
-
Assume that we are unsure about the probability of heads in a coin flip. To get an intuitive understanding of what "updating our beliefs" is, we will visualize the probability of heads in a coin flip after each observed evidence.
30
-
31
-
First, let us load some packages that we need to simulate a coin flip
20
+
First, let us load some packages that we need to simulate a coin flip:
32
21
33
22
```{julia}
34
23
using Distributions
@@ -43,8 +32,7 @@ and to visualize our results.
43
32
using StatsPlots
44
33
```
45
34
46
-
Note that Turing is not loaded here — we do not use it in this example. If you are already familiar with posterior updates, you can proceed to the next step.
47
-
35
+
Note that Turing is not loaded here — we do not use it in this example.
48
36
Next, we configure the data generating model. Let us set the true probability that a coin flip turns up heads
49
37
50
38
```{julia}
@@ -63,13 +51,20 @@ We simulate `N` coin flips by drawing N random samples from the Bernoulli distri
63
51
data = rand(Bernoulli(p_true), N);
64
52
```
65
53
66
-
Here is what the first five coin flips look like:
54
+
Here are the first five coin flips:
67
55
68
56
```{julia}
69
57
data[1:5]
70
58
```
71
59
72
-
Next, we specify a prior belief about the distribution of heads and tails in a coin toss. Here we choose a [Beta](https://en.wikipedia.org/wiki/Beta_distribution) distribution as prior distribution for the probability of heads. Before any coin flip is observed, we assume a uniform distribution $\operatorname{U}(0, 1) = \operatorname{Beta}(1, 1)$ of the probability of heads. I.e., every probability is equally likely initially.
60
+
61
+
### Coin Flipping Without Turing
62
+
63
+
The following example illustrates the effect of updating our beliefs with every piece of new evidence we observe.
64
+
65
+
Assume that we are unsure about the probability of heads in a coin flip. To get an intuitive understanding of what "updating our beliefs" is, we will visualize the probability of heads in a coin flip after each observed evidence.
66
+
67
+
We begin by specifying a prior belief about the distribution of heads and tails in a coin toss. Here we choose a [Beta](https://en.wikipedia.org/wiki/Beta_distribution) distribution as prior distribution for the probability of heads. Before any coin flip is observed, we assume a uniform distribution $\operatorname{U}(0, 1) = \operatorname{Beta}(1, 1)$ of the probability of heads. I.e., every probability is equally likely initially.
Copy file name to clipboardExpand all lines: tutorials/docs-00-getting-started/index.qmd
+29-54
Original file line number
Diff line number
Diff line change
@@ -16,96 +16,71 @@ Pkg.instantiate();
16
16
17
17
To use Turing, you need to install Julia first and then install Turing.
18
18
19
-
### Install Julia
19
+
You will need to install Julia 1.7 or greater, which you can get from [the official Julia website](http://julialang.org/downloads/).
20
20
21
-
You will need to install Julia 1.3 or greater, which you can get from [the official Julia website](http://julialang.org/downloads/).
22
-
23
-
### Install Turing.jl
24
-
25
-
Turing is an officially registered Julia package, so you can install a stable version of Turing by running the following in the Julia REPL:
21
+
Turing is officially registered in the [Julia General package registry](https://github.com/JuliaRegistries/General), which means that you can install a stable version of Turing by running the following in the Julia REPL:
26
22
27
23
```{julia}
24
+
#| eval: false
28
25
#| output: false
29
26
using Pkg
30
27
Pkg.add("Turing")
31
28
```
32
29
33
-
You can check if all tests pass by running `Pkg.test("Turing")` (it might take a long time)
34
-
35
-
### Example
36
-
37
-
Here's a simple example showing Turing in action.
30
+
### Example usage
38
31
39
-
First, we can load the Turing and StatsPlots modules
32
+
First, we load the Turing and StatsPlots modules.
33
+
The latter is required for visualising the results.
40
34
41
35
```{julia}
42
36
using Turing
43
37
using StatsPlots
44
38
```
45
39
46
-
Then, we define a simple Normal model with unknown mean and variance
40
+
We then specify our model, which is a simple Gaussian model with unknown mean and variance.
41
+
Models are defined as ordinary Julia functions, prefixed with the `@model` macro.
42
+
Each statement inside closely resembles how the model would be defined with mathematical notation.
43
+
Here, both `x` and `y` are observed values, and are therefore passed as function parameters.
44
+
`m` and `s²` are the parameters to be inferred.
47
45
48
46
```{julia}
49
47
@model function gdemo(x, y)
50
48
s² ~ InverseGamma(2, 3)
51
49
m ~ Normal(0, sqrt(s²))
52
50
x ~ Normal(m, sqrt(s²))
53
-
return y ~ Normal(m, sqrt(s²))
51
+
y ~ Normal(m, sqrt(s²))
54
52
end
55
53
```
56
54
57
-
Then we can run a sampler to collect results. In this case, it is a Hamiltonian Monte Carlo sampler
In this case, because we use the normal-inverse gamma distribution as a conjugate prior, we can compute its updated mean as follows:
63
+
We can plot the results:
70
64
71
65
```{julia}
72
-
s² = InverseGamma(2, 3)
73
-
m = Normal(0, 1)
74
-
data = [1.5, 2]
75
-
x_bar = mean(data)
76
-
N = length(data)
77
-
78
-
mean_exp = (m.σ * m.μ + N * x_bar) / (m.σ + N)
66
+
plot(chain)
79
67
```
80
68
81
-
We can also compute the updated variance
69
+
and obtain summary statistics by indexing the chain:
82
70
83
71
```{julia}
84
-
updated_alpha = shape(s²) + (N / 2)
85
-
updated_beta =
86
-
scale(s²) +
87
-
(1 / 2) * sum((data[n] - x_bar)^2 for n in 1:N) +
88
-
(N * m.σ) / (N + m.σ) * ((x_bar)^2) / 2
89
-
variance_exp = updated_beta / (updated_alpha - 1)
72
+
mean(chain[:m]), mean(chain[:s²])
90
73
```
91
74
92
-
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).
75
+
### Where to go next
93
76
94
-
```{julia}
95
-
function sample_posterior(alpha, beta, mean, lambda, iterations)
The underlying theory of Bayesian machine learning is not explained in detail in this documentation.
82
+
A thorough introduction to the field is [*Pattern Recognition and Machine Learning*](https://www.springer.com/us/book/9780387310732) (Bishop, 2006); an online version is available [here (PDF, 18.1 MB)](https://www.microsoft.com/en-us/research/uploads/prod/2006/01/Bishop-Pattern-Recognition-and-Machine-Learning-2006.pdf).
The next page on [Turing's core functionality](../../tutorials/docs-12-using-turing-guide/) explains the basic features of the Turing language.
86
+
From there, you can either look at [worked examples of how different models are implemented in Turing](../../tutorials/00-introduction/), or [specific tips and tricks that can help you get the most out of Turing](../../tutorials/docs-17-mode-estimation/).
0 commit comments