Skip to content

Commit af3d143

Browse files
penelopeysmpenelopeysm
authored
Modernise README (#2575)
* [no ci] Rework README * Re-add badges * [no ci] fix badges * [no ci] have more strongly worded discouragement for discussions * [no ci] add papers and bibtex * [no ci] add section on what's changed recently * Add getting started section * Implement review suggestions * Add Google Scholar cited-by link
1 parent 2d3f228 commit af3d143

File tree

2 files changed

+122
-12
lines changed

2 files changed

+122
-12
lines changed

‎.JuliaFormatter.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
style="blue"
22
format_markdown = true
33
import_to_using = false
4+
ignore = ["README.md"]

‎README.md

Lines changed: 121 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,129 @@
1-
# Turing.jl
1+
<p align="center"><img src="https://raw.githubusercontent.com/TuringLang/turinglang.github.io/refs/heads/main/assets/images/turing-logo.svg" alt="Turing.jl logo" width="200" /></p>
2+
<h1 align="center">Turing.jl</h1>
3+
<p align="center"><i>Probabilistic programming and Bayesian inference in Julia</i></p>
4+
<p align="center">
5+
<a href="https://turinglang.org/"><img src="https://img.shields.io/badge/docs-tutorials-blue.svg" alt="Tutorials" /></a>
6+
<a href="https://turinglang.org/Turing.jl/stable"><img src="https://img.shields.io/badge/docs-API-blue.svg" alt="API docs" /></a>
7+
<a href="https://github.com/TuringLang/Turing.jl/actions/workflows/Tests.yml"><img src="https://github.com/TuringLang/Turing.jl/actions/workflows/Tests.yml/badge.svg" alt="Tests" /></a>
8+
<a href="https://coveralls.io/github/TuringLang/Turing.jl?branch=main"><img src="https://coveralls.io/repos/github/TuringLang/Turing.jl/badge.svg?branch=main" alt="Coverage" /></a>
9+
<a href="https://github.com/SciML/ColPrac"><img src="https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet" alt="ColPrac: Contributor's Guide on Collaborative Practices for Community Packages" /></a>
10+
</p>
211

3-
[![Build Status](https://github.com/TuringLang/Turing.jl/workflows/Turing-CI/badge.svg)](https://github.com/TuringLang/Turing.jl/actions?query=workflow%3ATuring-CI+branch%3Amain)
4-
[![Coverage Status](https://coveralls.io/repos/github/TuringLang/Turing.jl/badge.svg?branch=main)](https://coveralls.io/github/TuringLang/Turing.jl?branch=main)
5-
[![codecov](https://codecov.io/gh/TuringLang/Turing.jl/branch/main/graph/badge.svg?token=OiUBsnDQqf)](https://codecov.io/gh/TuringLang/Turing.jl)
6-
[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
12+
## 🚀 Get started
713

8-
## Getting Started
14+
Install Julia (see [the official Julia website](https://julialang.org/install/); you will need at least Julia 1.10 will be required for the latest version of Turing.jl.
15+
Then, launch a Julia REPL and run:
916

10-
Turing's home page, with links to everything you'll need to use Turing, is available at:
17+
```julia
18+
julia> using Pkg; Pkg.add("Turing")
19+
```
1120

12-
https://turinglang.org/docs/
21+
You can define models using the `@model` macro, and then perform Markov chain Monte Carlo sampling using the `sample` function:
1322

14-
## What's changed recently?
23+
```julia
24+
julia> using Turing
1525

16-
See [releases](https://github.com/TuringLang/Turing.jl/releases).
26+
julia> @model function my_first_model(data)
27+
mean ~ Normal(0, 1)
28+
sd ~ truncated(Cauchy(0, 3); lower=0)
29+
data ~ Normal(mean, sd)
30+
end
1731

18-
## Issues and Discussions
32+
julia> model = my_first_model(randn())
1933

20-
Issues related to bugs and feature requests are welcome on the [issues page](https://github.com/TuringLang/Turing.jl/issues), while discussions and questions about statistical applications and theory should place on the [Discussions page](https://github.com/TuringLang/Turing.jl/discussions) or [our channel](https://julialang.slack.com/messages/turing/) (`#turing`) in the Julia Slack chat. If you do not have an invitation to Julia's Slack, you can get one by going [here](https://julialang.org/slack/).
34+
julia> chain = sample(model, NUTS(), 1000)
35+
```
36+
37+
You can find the main TuringLang documentation at [**https://turinglang.org**](https://turinglang.org), which contains general information about Turing.jl's features, as well as a variety of tutorials with examples of Turing.jl models.
38+
39+
API documentation for Turing.jl is specifically available at [**https://turinglang.org/Turing.jl/stable**](https://turinglang.org/Turing.jl/stable/).
40+
41+
## 🛠️ Contributing
42+
43+
### Issues
44+
45+
If you find any bugs or unintuitive behaviour when using Turing.jl, please do [open an issue](https://github.com/TuringLang/Turing.jl/issues)!
46+
Please don't worry about finding the correct repository for the issue; we can migrate the issue to the appropriate repository if we need to.
47+
48+
### Pull requests
49+
50+
We are of course also very happy to receive pull requests.
51+
If you are unsure about whether a particular feature would be welcome, you can open an issue for discussion first.
52+
53+
When opening a PR, non-breaking releases (patch versions) should target the `main` branch.
54+
Breaking releases (minor version) should target the `breaking` branch.
55+
56+
If you have not received any feedback on an issue or PR for a while, please feel free to ping `@TuringLang/maintainers` in a comment.
57+
58+
## 💬 Other channels
59+
60+
The Turing.jl userbase tends to be most active on the [`#turing` channel of Julia Slack](https://julialang.slack.com/archives/CCYDC34A0).
61+
If you do not have an invitation to Julia's Slack, you can get one from [the official Julia website](https://julialang.org/slack/).
62+
63+
There are also often threads on [Julia Discourse](https://discourse.julialang.org) (you can search using, e.g., [the `turing` tag](https://discourse.julialang.org/tag/turing)).
64+
65+
## 🔄 What's changed recently?
66+
67+
We publish a fortnightly newsletter summarising recent updates in the TuringLang ecosystem, which you can view on [our website](https://turinglang.org/news/), [GitHub](https://github.com/TuringLang/Turing.jl/issues/2498), or [Julia Slack](https://julialang.slack.com/archives/CCYDC34A0).
68+
69+
For Turing.jl specifically, you can see a full changelog in [`HISTORY.md`](https://github.com/TuringLang/Turing.jl/blob/main/HISTORY.md) or [our GitHub releases](https://github.com/TuringLang/Turing.jl/releases).
70+
71+
## 🧩 Where does Turing.jl sit in the TuringLang ecosystem?
72+
73+
Turing.jl is the main entry point for users, and seeks to provide a unified, convenient interface to all of the functionality in the TuringLang (and broader Julia) ecosystem.
74+
75+
In particular, it takes the ability to specify probabilistic models with [DynamicPPL.jl](https://github.com/TuringLang/DynamicPPL.jl), and combines it with a number of inference algorithms, such as:
76+
77+
- Markov Chain Monte Carlo (both an abstract interface: [AbstractMCMC.jl](https://github.com/TuringLang/AbstractMCMC.jl), and individual samplers, such as [AdvancedMH.jl](https://github.com/TuringLang/AdvancedMH.jl), [AdvancedHMC.jl](https://github.com/TuringLang/AdvancedHMC.jl), and more).
78+
- Variational inference using [AdvancedVI.jl](https://github.com/TuringLang/AdvancedVI.jl).
79+
- Maximum likelihood and maximum a posteriori estimation, which rely on SciML's [Optimization.jl interface](https://github.com/SciML/Optimization.jl).
80+
81+
## Citing Turing.jl
82+
83+
If you have used Turing.jl in your work, we would be very grateful if you could cite the following:
84+
85+
[**Turing.jl: a general-purpose probabilistic programming language**](https://doi.org/10.1145/3711897)
86+
Tor Erlend Fjelde, Kai Xu, David Widmann, Mohamed Tarek, Cameron Pfiffer, Martin Trapp, Seth D. Axen, Xianda Sun, Markus Hauru, Penelope Yong, Will Tebbutt, Zoubin Ghahramani, Hong Ge
87+
ACM Transactions on Probabilistic Machine Learning, 2025 (_Just Accepted_)
88+
89+
[**Turing: A Language for Flexible Probabilistic Inference**](https://proceedings.mlr.press/v84/ge18b.html)
90+
Hong Ge, Kai Xu, Zoubin Ghahramani
91+
Proceedings of the Twenty-First International Conference on Artificial Intelligence and Statistics, PMLR 84:1682-1690, 2018.
92+
93+
<details>
94+
95+
<summary>Expand for BibTeX</summary>
96+
97+
```bibtex
98+
@article{10.1145/3711897,
99+
author = {Fjelde, Tor Erlend and Xu, Kai and Widmann, David and Tarek, Mohamed and Pfiffer, Cameron and Trapp, Martin and Axen, Seth D. and Sun, Xianda and Hauru, Markus and Yong, Penelope and Tebbutt, Will and Ghahramani, Zoubin and Ge, Hong},
100+
title = {Turing.jl: a general-purpose probabilistic programming language},
101+
year = {2025},
102+
publisher = {Association for Computing Machinery},
103+
address = {New York, NY, USA},
104+
url = {https://doi.org/10.1145/3711897},
105+
doi = {10.1145/3711897},
106+
note = {Just Accepted},
107+
journal = {ACM Trans. Probab. Mach. Learn.},
108+
month = feb,
109+
}
110+
111+
@InProceedings{pmlr-v84-ge18b,
112+
title = {Turing: A Language for Flexible Probabilistic Inference},
113+
author = {Ge, Hong and Xu, Kai and Ghahramani, Zoubin},
114+
booktitle = {Proceedings of the Twenty-First International Conference on Artificial Intelligence and Statistics},
115+
pages = {1682--1690},
116+
year = {2018},
117+
editor = {Storkey, Amos and Perez-Cruz, Fernando},
118+
volume = {84},
119+
series = {Proceedings of Machine Learning Research},
120+
month = {09--11 Apr},
121+
publisher = {PMLR},
122+
pdf = {http://proceedings.mlr.press/v84/ge18b/ge18b.pdf},
123+
url = {https://proceedings.mlr.press/v84/ge18b.html},
124+
}
125+
```
126+
127+
</details>
128+
129+
You can see the full list of publications that have cited Turing.jl on [Google Scholar](https://scholar.google.com/scholar?cites=11803241473159708991).

0 commit comments

Comments
 (0)