Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proofread documentation #284

Merged
merged 2 commits into from
Apr 12, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ Inference with RxInfer | Inference with HMC
![](benchmarks/plots/inference_rxinfer.svg?raw=true&sanitize=true) | ![](benchmarks/plots/inference_turing.svg?raw=true&sanitize=true)

The benchmark and accuracy experiment, which generated these plots, is available in the `benchmarks/` folder. Note, that the execution speed and accuracy
of the HMC estimator heavily depends on the choice of hyper-parameters.
In this example, RxInfer executes exact inference consistently and does not depend on any hyper-parameters.
of the HMC estimator heavily depends on the choice of hyperparameters.
In this example, RxInfer executes exact inference consistently and does not depend on any hyperparameters.

### References

Expand Down
4 changes: 2 additions & 2 deletions docs/src/manuals/comparison.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# [Comparison to other packages](@id comparison)

Nowadays there's plenty of probabilistic programming languages and packages available. While all of them are based on Bayesian Inference, their methodologies vary. This section compares `RxInfer.jl` against other renowned probabilistic programming languages and packages. The goal is to enlighten potential users about the nuances and guide them in choosing the package that best suits their requirements.
Nowadays there's plenty of probabilistic programming languages and packages available. Although all are based on Bayesian inference, their methodologies vary. This section compares `RxInfer.jl` against other renowned probabilistic programming languages and packages. The goal is to enlighten potential users about the nuances and guide them in choosing the package that best suits their requirements.

!!! warning
1. This comparison isn't exhaustive and mirrors the author's hands-on experience with the packages. Some might have undergone more rigorous testing than others. If you're an author of one of these packages and believe the comparison doesn't do justice, please [reach out](https://github.com/ReactiveBayes), and we'll be more than willing to rectify.
1. This comparison is not exhaustive and mirrors the author's hands-on experience with the packages. Others may have undergone more rigorous testing. If you're an author of one of these packages and believe this comparison does not do justice, please [reach out](https://github.com/ReactiveBayes), and we will be more than willing to make corrections.
2. The comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.


Expand Down
2 changes: 1 addition & 1 deletion docs/src/manuals/constraints-specification.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# [Constraints Specification](@id user-guide-constraints-specification)

`RxInfer.jl` uses a macro called `@constraints` from `GraphPPL` to add extra constraints during the inference process. For details on how to use the `@constraints` macro, you can check out the [official documentation](https://reactivebayes.github.io/GraphPPL.jl/stable/) of GraphPPL.
`RxInfer.jl` uses a macro called `@constraints` from `GraphPPL` to add extra constraints during the inference process. For details on using the `@constraints` macro, you can check out the [official documentation](https://reactivebayes.github.io/GraphPPL.jl/stable/) of GraphPPL.

## [Background and example](@id user-guide-constraints-specification-background)

Expand Down
2 changes: 1 addition & 1 deletion docs/src/manuals/debugging.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# [Debugging](@id user-guide-debugging)

Debugging inference in `RxInfer` can be quite challenging, mostly due to reactive nature of the inference, undefiend order of computations, the use of observables and Julia's hard-to-read stack traces in general. Below we discuss ways to help you find problems in your model that prevents you from getting the results you want.
Debugging inference in `RxInfer` can be quite challenging, mostly due to the reactive nature of the inference, undefined order of computations, the use of observables, and generally hard-to-read stack traces in Julia. Below we discuss ways to help you find problems in your model that prevents you from getting the results you want.

## Requesting a trace of messages

Expand Down
2 changes: 1 addition & 1 deletion docs/src/manuals/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ Sometimes the data is not known at model creation time, for example, during reac
For that purpose `RxInfer` uses [`RxInfer.DefferedDataHandler`](@ref) structure.

```@example coin
# The only difference here is that we do not specify `a` and `b` as hyper-parameters
# The only difference here is that we do not specify `a` and `b` as hyperparameters
# But rather indicate that the data for them will be available later during the inference
conditioned_with_deffered_data = coin_model() | (
y = [ 1.0, 0.0, 1.0 ],
Expand Down
6 changes: 3 additions & 3 deletions docs/src/manuals/inference/delta-node.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# [Deterministic nodes](@id delta-node-manual)

RxInfer.jl offers a comprehensive set of stochastic nodes, with a primary emphasis on distributions from the exponential family and its associated compositions, such as Gaussian with controlled variance (GCV) or autoregressive (AR) nodes. The `DeltaNode` stands out in this package, representing a deterministic transformation of either a single random variable or a group of them. This guide provides insights into the `DeltaNode` and its functionalities.
RxInfer.jl offers a comprehensive set of stochastic nodes, primarily emphasizing distributions from the exponential family and related compositions, such as Gaussian with controlled variance (GCV) or autoregressive (AR) nodes. The `DeltaNode` stands out in this package, representing a deterministic transformation of either a single random variable or a group of them. This guide provides insights into the `DeltaNode` and its functionalities.

## Features and Supported Inference Scenarios

The delta node has several approximation methods for performing probabilistic inference. The desired approximation method depends on the nodes connected to the delta node. We differentiate the following deterministic transformation scenarios:
The delta node supports several approximation methods for probabilistic inference. The desired approximation method depends on the nodes connected to the delta node. We differentiate the following deterministic transformation scenarios:

1. **Gaussian Nodes**: For delta nodes linked to strictly multivariate or univariate Gaussian distributions, the recommended methods are Linearization or Unscented transforms.
2. **Exponential Family Nodes**: For the delta node connected to nodes from the exponential family, the CVI (Conjugate Variational Inference) is the method of choice.
Expand All @@ -20,7 +20,7 @@ The table below summarizes the features of the delta node in RxInfer.jl, categor

## Gaussian Case

In the context of Gaussian distributions, we recommend either the `Linearization` or `Unscented` method for delta node approximation. The `Linearization` method provides a first-order approximation, while the `Unscented` method delivers a more precise second-order approximation. It's worth noting that while the `Unscented` method is more accurate, it may require hyper-parameters tuning.
In the context of Gaussian distributions, we recommend either the `Linearization` or `Unscented` method for delta node approximation. The `Linearization` method provides a first-order approximation, while the `Unscented` method delivers a more precise second-order approximation. It's worth noting that while the `Unscented` method is more accurate, it may require hyperparameters tuning.


For clarity, consider the following example:
Expand Down
4 changes: 2 additions & 2 deletions docs/src/manuals/inference/initialization.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# [Understating why we need to initialize posteriors or messages in RxInfer](@id initialization)

In certain models, after completing the model specification step and moving on to execute the inference procedure, you may encounter an error prompting you to _initialize required marginals and messages_. Understanding why this step is necessary can be perplexing. This tutorial is designed to delve into the intuition behind model initialization using a practical example.
In certain models, after completing the model specification step and moving on to execute the inference procedure, you may encounter an error prompting you to _initialize required marginals and messages_. Understanding why this step is necessary can be perplexing. This tutorial is designed to explore the intuition behind model initialization using a practical example

```@docs
@initialization
Expand Down Expand Up @@ -30,7 +30,7 @@ ylabel!("Fuel consumption")

### Univariate regression with known noise

First, he drives the car on a urban road. John enjoys driving on the well-built, wide, and flat urban roads. Urban roads also offer the advantage of precise fuel consumption measurement with minimal noise. Therefore John models the fuel consumption $y_n\in\mathbb{R}$ as a normal distribution and treats $x_n$ as a fixed hyper-parameter:
First, he drives the car on a urban road. John enjoys driving on the well-built, wide, and flat urban roads. Urban roads also offer the advantage of precise fuel consumption measurement with minimal noise. Therefore John models the fuel consumption $y_n\in\mathbb{R}$ as a normal distribution and treats $x_n$ as a fixed hyperparameter:

$$\begin{aligned}
p(y_n \mid a, b) = \mathcal{N}(y_n \mid a x_n + b , 1)
Expand Down
8 changes: 4 additions & 4 deletions docs/src/manuals/inference/overview.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# [Inference execution](@id user-guide-inference-execution)

The `RxInfer` inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):
The `RxInfer` inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types). While `RxInfer` implements several algorithms to cater to different computational needs and scenarios, the core message-passing algorithms that form the foundation of our inference capabilities are:

- [Belief Propagation](https://en.wikipedia.org/wiki/Belief_propagation)
- [Variational Message Passing](https://en.wikipedia.org/wiki/Variational_message_passing)

Whereas belief propagation computes exact inference for the random variables of interest, the variational message passing (VMP) in an approximation method that can be applied to a larger range of models.
Whereas belief propagation computes exact inference for the random variables of interest, the variational message passing (VMP) is an approximation method that can be applied to a larger range of models.

The inference engine itself isn't aware of different algorithm types and simply does message passing between nodes, however during model specification stage user may specify different factorisation constraints around factor nodes with the help of the [`@constraints`](@ref user-guide-constraints-specification) macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding [section](@ref user-guide-constraints-specification).
The inference engine itself isn't aware of different algorithm types and simply does message passing between nodes. However, during the model specification stage user may specify different factorisation constraints around factor nodes with the help of the [`@constraints`](@ref user-guide-constraints-specification) macro. Different factorisation constraints lead to different message passing update rules. See more documentation about constraints specification in the corresponding [section](@ref user-guide-constraints-specification).

## [Automatic inference specification](@id user-guide-inference-execution-automatic-specification)

`RxInfer` exports the [`infer`](@ref) function to quickly run and test you model with both static and asynchronous (real-time) datasets. See more information about the [`infer`](@ref) function on the separate documentation section:
`RxInfer` exports the [`infer`](@ref) function to quickly run and test your model with both static and asynchronous (real-time) datasets. See more information about the [`infer`](@ref) function on the separate documentation section:

- [Static Inference](@ref manual-static-inference)
- [Streamlined Inference](@ref manual-online-inference)
Expand Down
11 changes: 5 additions & 6 deletions docs/src/manuals/inference/streamlined.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# [Streaming (online) inference](@id manual-online-inference)

This guide explains how to use the [`infer`](@ref) function for dynamic datasets. We'll show how `RxInfer` can continuously update beliefs asynchronously whenever a new observation arrives. We'll use a simple Beta-Bernoulli model as an example, which has been covered in the [Getting Started](@ref user-guide-getting-started) section,
but keep in mind that these techniques can apply to any model.
This guide explains how to use the [`infer`](@ref) function for dynamic datasets. We show how `RxInfer` can continuously update beliefs asynchronously whenever a new observation arrives. We use a simple Beta-Bernoulli model as an example, which has been covered in the [Getting Started](@ref user-guide-getting-started) section,
however, these techniques can be applied to any model

Also read about [Static Inference](@ref manual-static-inference) or checkout more complex [examples](https://reactivebayes.github.io/RxInfer.jl/stable/examples/overview/).

Expand Down Expand Up @@ -36,16 +36,15 @@ beta_bernoulli_autoupdates = @autoupdates begin
end
```

This specification instructs `RxInfer` to update `a` and `b` parameters automatically as as soon as new posterior for `θ` is available.
This specification instructs `RxInfer` to update `a` and `b` parameters automatically as as soon as a new posterior for `θ` is available.

```@docs
@autoupdates
```

## [Asynchronous data stream of observations](@id manual-online-inference-async-datastream)

For demonstration purposes, we will use hand crafted stream of observations using the `Rocket.jl` library:

For demonstration purposes, we use a handcrafted stream of observations with the `Rocket.jl` library
```@example manual-online-inference
using Rocket, Distributions, StableRNGs

Expand All @@ -55,7 +54,7 @@ rng = StableRNG(43)
datastream = RecentSubject(Bool)
```

The [`infer`](@ref) function expects the `datastream` to emit values in the form of the `NamedTuple`s. To simply this process, `Rocket.jl` exports `labeled` function. We also use the `combineLatest` function to convert a stream of `Bool`s to a stream of `Tuple{Bool}`s. Read more about these function in the [documentation to `Rocket.jl`](https://reactivebayes.github.io/Rocket.jl/stable/).
The [`infer`](@ref) function expects the `datastream` to emit values in the form of the `NamedTuple`s. To simplify this process, `Rocket.jl` exports `labeled` function. We also use the `combineLatest` function to convert a stream of `Bool`s to a stream of `Tuple{Bool}`s. Read more about these function in the [documentation to `Rocket.jl`](https://reactivebayes.github.io/Rocket.jl/stable/).

```@example manual-online-inference
observations = labeled(Val((:y, )), combineLatest(datastream))
Expand Down
2 changes: 1 addition & 1 deletion docs/src/manuals/meta-specification.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# [Meta Specification](@id user-guide-meta-specification)

`RxInfer.jl` utilizes the `GraphPPL.jl` package to construct a factor graph representing a probabilistic model, and then employs the `ReactiveMP.jl` package to conduct variational inference through message passing on this factor graph. Some factor nodes within the `ReactiveMP.jl` inference engine require additional structure, known as meta-information. This meta-information can serve various purposes such as providing extra details to nodes, customizing the inference process, or adjusting how nodes compute outgoing messages. For example, the `AR` node, which models _Auto-Regressive_ processes, needs to know the order of the `AR` process. Similarly, the `GCV` node ([Gaussian Controlled Variance](https://ieeexplore.ieee.org/document/9173980)) requires an approximation method to handle non-conjugate relationships between its variables. To address these needs, `RxInfer.jl` utilizes the `@meta` macro from the `GraphPPL.jl` package to specify node-specific meta-information and contextual details.
`RxInfer.jl` utilizes the `GraphPPL.jl` package to construct a factor graph representing a probabilistic model, and then employs the `ReactiveMP.jl` package to conduct variational inference through message passing on this factor graph. Some factor nodes within the `ReactiveMP.jl` inference engine require an additional structure, known as meta-information. This meta-information can serve various purposes such as providing extra details to nodes, customizing the inference process, or adjusting how nodes compute outgoing messages. For example, the `AR` node, which models _Auto-Regressive_ processes, needs to know the order of the `AR` process. Similarly, the `GCV` node ([Gaussian Controlled Variance](https://ieeexplore.ieee.org/document/9173980)) requires an approximation method to handle non-conjugate relationships between its variables. To address these needs, `RxInfer.jl` utilizes the `@meta` macro from the `GraphPPL.jl` package to specify node-specific meta-information and contextual details.

Here, we only touch upon the basics of the `@meta` macro. For further details, please consult the [official documentation](https://reactivebayes.github.io/GraphPPL.jl/stable/) of the GraphPPL.jl package.

Expand Down
2 changes: 1 addition & 1 deletion docs/src/manuals/model-specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ prespecified `variance` hyperparameter.
`length(y)` can be called only if `y` has an associated data with it. This is not always the case, for example it is possible to instantiate the
model lazily before the data becomes available. In such situations, `length(y)` will throw an error.

### [Hyper-parameters](@id user-guide-model-specification-hyperparameters)
### [Hyperparameters](@id user-guide-model-specification-hyperparameters)

Any constant passed to a model as a model argument will be automatically converted to a corresponding constant node in the model's graph.

Expand Down
2 changes: 1 addition & 1 deletion examples/advanced_examples/GP Regression by SSM.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -724,7 +724,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"As we can see from the plot, both cases of Matern kernel provide good approximations (small variance) to the true process at the area with dense observations (namely from t = 0 to around 3.5), and when we move far away from this region the approximated processes become less accurate (larger variance). This result makes sense because GP regression exploits the correlation between observations to predict unobserved points, and the choice of covariance functions as well as their hyper-parameters might not be optimal. We can increase the accuracy of the approximated processes by simply adding more observations. This way of improvement does not trouble the state-space method much but it might cause computational problem for naive GP regression, because with N observations the complexity of naive GP regression scales with $N^3$ while the state-space method scales linearly with N. "
"As we can see from the plot, both cases of Matern kernel provide good approximations (small variance) to the true process at the area with dense observations (namely from t = 0 to around 3.5), and when we move far away from this region the approximated processes become less accurate (larger variance). This result makes sense because GP regression exploits the correlation between observations to predict unobserved points, and the choice of covariance functions as well as their hyperparameters might not be optimal. We can increase the accuracy of the approximated processes by simply adding more observations. This way of improvement does not trouble the state-space method much but it might cause computational problem for naive GP regression, because with N observations the complexity of naive GP regression scales with $N^3$ while the state-space method scales linearly with N. "
]
}
],
Expand Down
Loading
Loading