Skip to content

Commit 625a9c8

Browse files
penelopeysmgithub-actions[bot]mhauru
authored
Clean up exports (#2474)
* Regroup exports by package * Export DynamicPPL.returned and DynamicPPL.prefix * Stop exporting @logprob_str and @prob_str * Remove DynamicPPL module export * Remove DynamicPPL.LogDensityFunction re-export * Remove BernoulliLogit, drop support for Distributions < 0.25.77 * Stop blanket re-exporting Libtask and Bijectors * Manually specify AbstractMCMC exports * Format Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Remove Bijectors.ordered export * Re-export LinearAlgebra.I * Replace Turing.Model -> DynamicPPL.Model * Format * Keep exporting LogDensityFunction * Add note in docs * Align Turing exports with docs API page * Fix things like `predict` on docs API page * Fix a Gibbs test * Format * Fix missing Bijectors import * Update docs/src/api.md Co-authored-by: Markus Hauru <[email protected]> * Update docs/src/api.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Clean up broken docs links, remove unneeded deps * Format * Add changelog entry for exports * Clean up exports in essential/Essential * Apply suggestions from code review Co-authored-by: Markus Hauru <[email protected]> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Markus Hauru <[email protected]> Co-authored-by: Markus Hauru <[email protected]>
1 parent e842e30 commit 625a9c8

File tree

21 files changed

+139
-150
lines changed

21 files changed

+139
-150
lines changed

‎HISTORY.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,22 @@ Turing.jl v0.37 uses DynamicPPL v0.35, which brings with it several breaking cha
2323

2424
For more details about all of the above, see the changelog of DynamicPPL [here](https://github.com/TuringLang/DynamicPPL.jl/releases/tag/v0.35.0).
2525

26+
### Export list
27+
28+
Turing.jl's export list has been cleaned up a fair bit. This affects what is imported into your namespace when you do an unqualified `using Turing`. You may need to import things more explicitly than before.
29+
30+
- The `DynamicPPL` and `AbstractMCMC` modules are no longer exported. You will need to `import DynamicPPL` or `using DynamicPPL: DynamicPPL` (likewise `AbstractMCMC`) yourself, which in turn means that they have to be made available in your project environment.
31+
32+
- `@logprob_str` and `@prob_str` have been removed following a long deprecation period.
33+
- We no longer re-export everything from `Bijectors` and `Libtask`. To get around this, add `using Bijectors` or `using Libtask` at the top of your script (but we recommend using more selective imports).
34+
35+
+ We no longer export `Bijectors.ordered`. If you were using `ordered`, even Bijectors does not (currently) export this. You will have to manually import it with `using Bijectors: ordered`.
36+
37+
On the other hand, we have added a few more exports:
38+
39+
- `DynamicPPL.returned` and `DynamicPPL.prefix` are exported (for use with submodels).
40+
- `LinearAlgebra.I` is exported for convenience.
41+
2642
# Release 0.36.0
2743

2844
## Breaking changes

‎Project.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ BangBang = "0.4.2"
5858
Bijectors = "0.14, 0.15"
5959
Compat = "4.15.0"
6060
DataStructures = "0.18"
61-
Distributions = "0.23.3, 0.24, 0.25"
61+
Distributions = "0.25.77"
6262
DistributionsAD = "0.6"
6363
DocStringExtensions = "0.8, 0.9"
6464
DynamicHMC = "3.4"

‎docs/Project.toml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
11
[deps]
2-
Bijectors = "76274a88-744f-5084-9051-94815aaf08c4"
3-
Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
42
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
53
DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
6-
DynamicPPL = "366bfd00-2699-11ea-058f-f148b4cae6d8"
74
Turing = "fce5fe82-541a-59a6-adf8-730c64b5f9a0"

‎docs/make.jl‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,32 @@
11
using Documenter
22
using Turing
3-
# Need to import Distributions and Bijectors to generate docs for functions
4-
# from those packages.
5-
using Distributions
6-
using Bijectors
7-
using DynamicPPL
83

94
using DocumenterInterLinks
105

116
links = InterLinks(
127
"DynamicPPL" => "https://turinglang.org/DynamicPPL.jl/stable/objects.inv",
13-
"AbstractPPL" => "https://turinglang.org/AbstractPPL.jl/dev/objects.inv",
8+
"AbstractPPL" => "https://turinglang.org/AbstractPPL.jl/stable/objects.inv",
9+
"LinearAlgebra" => "https://docs.julialang.org/en/v1/objects.inv",
10+
"AbstractMCMC" => "https://turinglang.org/AbstractMCMC.jl/stable/objects.inv",
1411
"ADTypes" => "https://sciml.github.io/ADTypes.jl/stable/objects.inv",
1512
"AdvancedVI" => "https://turinglang.org/AdvancedVI.jl/v0.2.8/objects.inv",
1613
"DistributionsAD" => "https://turinglang.org/DistributionsAD.jl/stable/objects.inv",
14+
"OrderedCollections" => "https://juliacollections.github.io/OrderedCollections.jl/stable/objects.inv",
1715
)
1816

1917
# Doctest setup
2018
DocMeta.setdocmeta!(Turing, :DocTestSetup, :(using Turing); recursive=true)
2119

2220
makedocs(;
2321
sitename="Turing",
24-
modules=[Turing, Distributions, Bijectors],
22+
modules=[Turing],
2523
pages=[
2624
"Home" => "index.md",
2725
"API" => "api.md",
2826
"Submodule APIs" =>
2927
["Inference" => "api/Inference.md", "Optimisation" => "api/Optimisation.md"],
3028
],
3129
checkdocs=:exports,
32-
# checkdocs_ignored_modules=[Turing, Distributions, DynamicPPL, AbstractPPL, Bijectors],
3330
doctest=false,
3431
warnonly=true,
3532
plugins=[links],

‎docs/src/api.md‎

Lines changed: 32 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,13 @@ Turing.jl directly re-exports the entire public API of the following packages:
66

77
- [Distributions.jl](https://juliastats.org/Distributions.jl)
88
- [MCMCChains.jl](https://turinglang.org/MCMCChains.jl)
9-
- [AbstractMCMC.jl](https://turinglang.org/AbstractMCMC.jl)
10-
- [Bijectors.jl](https://turinglang.org/Bijectors.jl)
11-
- [Libtask.jl](https://github.com/TuringLang/Libtask.jl)
129

1310
Please see the individual packages for their documentation.
1411

1512
## Individual exports and re-exports
1613

17-
**All** of the following symbols are exported unqualified by Turing, even though the documentation suggests that many of them are qualified.
14+
In this API documentation, for the sake of clarity, we have listed the module that actually defines each of the exported symbols.
15+
Note, however, that **all** of the following symbols are exported unqualified by Turing.
1816
That means, for example, you can just write
1917

2018
```julia
@@ -37,17 +35,22 @@ even though [`Prior()`](@ref) is actually defined in the `Turing.Inference` modu
3735

3836
### Modelling
3937

40-
| Exported symbol | Documentation | Description |
41-
|:--------------- |:----------------------------------- |:-------------------------------------------- |
42-
| `@model` | [`DynamicPPL.@model`](@extref) | Define a probabilistic model |
43-
| `@varname` | [`AbstractPPL.@varname`](@extref) | Generate a `VarName` from a Julia expression |
44-
| `to_submodel` | [`DynamicPPL.to_submodel`](@extref) | Define a submodel |
38+
| Exported symbol | Documentation | Description |
39+
|:-------------------- |:------------------------------------------ |:-------------------------------------------------------------------------------------------- |
40+
| `@model` | [`DynamicPPL.@model`](@extref) | Define a probabilistic model |
41+
| `@varname` | [`AbstractPPL.@varname`](@extref) | Generate a `VarName` from a Julia expression |
42+
| `to_submodel` | [`DynamicPPL.to_submodel`](@extref) | Define a submodel |
43+
| `prefix` | [`DynamicPPL.prefix`](@extref) | Prefix all variable names in a model with a given symbol |
44+
| `LogDensityFunction` | [`DynamicPPL.LogDensityFunction`](@extref) | A struct containing all information about how to evaluate a model. Mostly for advanced users |
4545

4646
### Inference
4747

48-
| Exported symbol | Documentation | Description |
49-
|:--------------- |:------------------------------------------------------------------------------------------------ |:------------------- |
50-
| `sample` | [`StatsBase.sample`](https://turinglang.org/AbstractMCMC.jl/stable/api/#Sampling-a-single-chain) | Sample from a model |
48+
| Exported symbol | Documentation | Description |
49+
|:----------------- |:------------------------------------------------------------------------------------------------ |:---------------------------------- |
50+
| `sample` | [`StatsBase.sample`](https://turinglang.org/AbstractMCMC.jl/stable/api/#Sampling-a-single-chain) | Sample from a model |
51+
| `MCMCThreads` | [`AbstractMCMC.MCMCThreads`](@extref) | Run MCMC using multiple threads |
52+
| `MCMCDistributed` | [`AbstractMCMC.MCMCDistributed`](@extref) | Run MCMC using multiple processes |
53+
| `MCMCSerial` | [`AbstractMCMC.MCMCSerial`](@extref) | Run MCMC using without parallelism |
5154

5255
### Samplers
5356

@@ -68,6 +71,7 @@ even though [`Prior()`](@ref) is actually defined in the `Turing.Inference` modu
6871
| `SMC` | [`Turing.Inference.SMC`](@ref) | Sequential Monte Carlo |
6972
| `PG` | [`Turing.Inference.PG`](@ref) | Particle Gibbs |
7073
| `CSMC` | [`Turing.Inference.CSMC`](@ref) | The same as PG |
74+
| `RepeatSampler` | [`Turing.Inference.RepeatSampler`](@ref) | A sampler that runs multiple times on the same variable |
7175
| `externalsampler` | [`Turing.Inference.externalsampler`](@ref) | Wrap an external sampler for use in Turing |
7276

7377
### Variational inference
@@ -108,52 +112,37 @@ OrderedLogistic
108112
LogPoisson
109113
```
110114

111-
`BernoulliLogit` is part of Distributions.jl since version 0.25.77.
112-
If you are using an older version of Distributions where this isn't defined, Turing will export the same distribution.
113-
114-
```@docs
115-
Distributions.BernoulliLogit
116-
```
117-
118115
### Tools to work with distributions
119116

120117
| Exported symbol | Documentation | Description |
121118
|:--------------- |:-------------------------------------- |:-------------------------------------------------------------- |
119+
| `I` | [`LinearAlgebra.I`](@extref) | Identity matrix |
122120
| `filldist` | [`DistributionsAD.filldist`](@extref) | Create a product distribution from a distribution and integers |
123121
| `arraydist` | [`DistributionsAD.arraydist`](@extref) | Create a product distribution from an array of distributions |
124122
| `NamedDist` | [`DynamicPPL.NamedDist`](@extref) | A distribution that carries the name of the variable |
125123

126124
### Predictions
127125

128-
```@docs
129-
DynamicPPL.predict
130-
```
126+
| Exported symbol | Documentation | Description |
127+
|:--------------- |:--------------------------------------------------------------------------------- |:------------------------------------------------------- |
128+
| `predict` | [`StatsAPI.predict`](https://turinglang.org/DynamicPPL.jl/stable/api/#Predicting) | Generate samples from posterior predictive distribution |
131129

132130
### Querying model probabilities and quantities
133131

134132
Please see the [generated quantities](https://turinglang.org/docs/tutorials/usage-generated-quantities/) and [probability interface](https://turinglang.org/docs/tutorials/usage-probability-interface/) guides for more information.
135133

136-
| Exported symbol | Documentation | Description |
137-
|:-------------------------- |:--------------------------------------------------------------------------------------------------------------------------------- |:--------------------------------------------------------------- |
138-
| `generated_quantities` | [`DynamicPPL.generated_quantities`](@extref) | Calculate additional quantities defined in a model |
139-
| `pointwise_loglikelihoods` | [`DynamicPPL.pointwise_loglikelihoods`](@extref) | Compute log likelihoods for each sample in a chain |
140-
| `logprior` | [`DynamicPPL.logprior`](@extref) | Compute log prior probability |
141-
| `logjoint` | [`DynamicPPL.logjoint`](@extref) | Compute log joint probability |
142-
| `LogDensityFunction` | [`DynamicPPL.LogDensityFunction`](@extref) | Wrap a Turing model to satisfy LogDensityFunctions.jl interface |
143-
| `condition` | [`AbstractPPL.condition`](@extref) | Condition a model on data |
144-
| `decondition` | [`AbstractPPL.decondition`](@extref) | Remove conditioning on data |
145-
| `conditioned` | [`DynamicPPL.conditioned`](@extref) | Return the conditioned values of a model |
146-
| `fix` | [`DynamicPPL.fix`](@extref) | Fix the value of a variable |
147-
| `unfix` | [`DynamicPPL.unfix`](@extref) | Unfix the value of a variable |
148-
| `OrderedDict` | [`OrderedCollections.OrderedDict`](https://juliacollections.github.io/OrderedCollections.jl/dev/ordered_containers/#OrderedDicts) | An ordered dictionary |
149-
150-
### Extra re-exports from Bijectors
151-
152-
Note that Bijectors itself does not export `ordered`.
153-
154-
```@docs
155-
Bijectors.ordered
156-
```
134+
| Exported symbol | Documentation | Description |
135+
|:-------------------------- |:---------------------------------------------------------------------------------------------------------------------------- |:-------------------------------------------------- |
136+
| `returned` | [`DynamicPPL.returned`](https://turinglang.org/DynamicPPL.jl/stable/api/#DynamicPPL.returned-Tuple%7BModel,%20NamedTuple%7D) | Calculate additional quantities defined in a model |
137+
| `pointwise_loglikelihoods` | [`DynamicPPL.pointwise_loglikelihoods`](@extref) | Compute log likelihoods for each sample in a chain |
138+
| `logprior` | [`DynamicPPL.logprior`](@extref) | Compute log prior probability |
139+
| `logjoint` | [`DynamicPPL.logjoint`](@extref) | Compute log joint probability |
140+
| `condition` | [`AbstractPPL.condition`](@extref) | Condition a model on data |
141+
| `decondition` | [`AbstractPPL.decondition`](@extref) | Remove conditioning on data |
142+
| `conditioned` | [`DynamicPPL.conditioned`](@extref) | Return the conditioned values of a model |
143+
| `fix` | [`DynamicPPL.fix`](@extref) | Fix the value of a variable |
144+
| `unfix` | [`DynamicPPL.unfix`](@extref) | Unfix the value of a variable |
145+
| `OrderedDict` | [`OrderedCollections.OrderedDict`](@extref) | An ordered dictionary |
157146

158147
### Point estimates
159148

‎src/Turing.jl‎

Lines changed: 48 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,24 @@ using Reexport, ForwardDiff
44
using DistributionsAD, Bijectors, StatsFuns, SpecialFunctions
55
using Statistics, LinearAlgebra
66
using Libtask
7-
@reexport using Distributions, MCMCChains, Libtask, AbstractMCMC, Bijectors
7+
@reexport using Distributions, MCMCChains
88
using Compat: pkgversion
99

1010
using AdvancedVI: AdvancedVI
11-
using DynamicPPL: DynamicPPL, LogDensityFunction
11+
using DynamicPPL: DynamicPPL
1212
import DynamicPPL: NoDist, NamedDist
1313
using LogDensityProblems: LogDensityProblems
1414
using NamedArrays: NamedArrays
1515
using Accessors: Accessors
1616
using StatsAPI: StatsAPI
1717
using StatsBase: StatsBase
18+
using AbstractMCMC
1819

1920
using Accessors: Accessors
2021

2122
using Printf: Printf
2223
using Random: Random
24+
using LinearAlgebra: I
2325

2426
using ADTypes: ADTypes
2527

@@ -64,75 +66,91 @@ include("deprecated.jl") # to be removed in the next minor version release
6466
using DynamicPPL:
6567
pointwise_loglikelihoods,
6668
generated_quantities,
69+
returned,
6770
logprior,
6871
logjoint,
6972
condition,
7073
decondition,
7174
fix,
7275
unfix,
7376
conditioned,
74-
to_submodel
77+
to_submodel,
78+
LogDensityFunction
7579
using StatsBase: predict
76-
using Bijectors: ordered
7780
using OrderedCollections: OrderedDict
7881

7982
# Turing essentials - modelling macros and inference algorithms
80-
export @model, # modelling
83+
export
84+
# DEPRECATED
85+
@submodel,
86+
generated_quantities,
87+
# Modelling - AbstractPPL and DynamicPPL
88+
@model,
8189
@varname,
82-
@submodel, # Deprecated
8390
to_submodel,
84-
DynamicPPL,
85-
Prior, # Sampling from the prior
86-
MH, # classic sampling
91+
prefix,
92+
LogDensityFunction,
93+
# Sampling - AbstractMCMC
94+
sample,
95+
MCMCThreads,
96+
MCMCDistributed,
97+
MCMCSerial,
98+
# Samplers - Turing.Inference
99+
Prior,
100+
MH,
87101
Emcee,
88102
ESS,
89103
Gibbs,
90-
HMC, # Hamiltonian-like sampling
104+
HMC,
91105
SGLD,
92106
SGHMC,
107+
PolynomialStepsize,
93108
HMCDA,
94109
NUTS,
95-
PolynomialStepsize,
96-
IS, # particle-based sampling
110+
IS,
97111
SMC,
98-
CSMC,
99112
PG,
113+
CSMC,
100114
RepeatSampler,
101-
vi, # variational inference
102-
ADVI,
103-
sample, # inference
104-
@logprob_str, # TODO: Remove, see https://github.com/TuringLang/DynamicPPL.jl/issues/356
105-
@prob_str, # TODO: Remove, see https://github.com/TuringLang/DynamicPPL.jl/issues/356
106115
externalsampler,
107-
AutoForwardDiff, # ADTypes
116+
# Variational inference - AdvancedVI
117+
vi,
118+
ADVI,
119+
# ADTypes
120+
AutoForwardDiff,
108121
AutoReverseDiff,
109122
AutoMooncake,
110-
setprogress!, # debugging
123+
# Debugging - Turing
124+
setprogress!,
125+
# Distributions
111126
Flat,
112127
FlatPos,
113128
BinomialLogit,
114-
BernoulliLogit, # Part of Distributions >= 0.25.77
115129
OrderedLogistic,
116130
LogPoisson,
117-
filldist,
118-
arraydist,
119-
NamedDist, # Exports from DynamicPPL
131+
# Tools to work with Distributions
132+
I, # LinearAlgebra
133+
filldist, # DistributionsAD
134+
arraydist, # DistributionsAD
135+
NamedDist, # DynamicPPL
136+
# Predictions - DynamicPPL
120137
predict,
138+
# Querying model probabilities - DynamicPPL
139+
returned,
121140
pointwise_loglikelihoods,
122-
generated_quantities,
123141
logprior,
142+
loglikelihood,
124143
logjoint,
125-
LogDensityFunction,
126144
condition,
127145
decondition,
146+
conditioned,
128147
fix,
129148
unfix,
130-
conditioned,
131-
OrderedDict,
132-
ordered, # Exports from Bijectors
149+
OrderedDict, # OrderedCollections
150+
# Point estimates - Turing.Optimisation
151+
# The MAP and MLE exports are only needed for the Optim.jl interface.
133152
maximum_a_posteriori,
134153
maximum_likelihood,
135-
# The MAP and MLE exports are only needed for the Optim.jl interface.
136154
MAP,
137155
MLE
138156

0 commit comments

Comments
 (0)