Add sharp bits section and invite users to the discussions upon error #391

bvdmitri · 2024-12-18T10:17:14Z

This was on our issue tracker for a while, but with the help of Cursor things get easier. Please review and suggest changes.

This pull request introduces several updates to the RxInfer documentation, focusing on improving user guidance and addressing common issues. The changes include adding a new "Sharp bits of RxInfer" section, updating the documentation to include references to this new section, and enhancing error handling and messaging within the inference process.

Documentation improvements:

docs/make.jl: Introduced a draft mode for documentation generation, and added a new section "Sharp bits of RxInfer" to the documentation index. [1] [2]
docs/src/manuals/comparison.md: Added a note about using := for deterministic relationships in RxInfer.
docs/src/manuals/model-specification.md: Included a reference to the new "Sharp bits" section for further explanation on deterministic nodes.

New "Sharp bits of RxInfer" section:

docs/src/manuals/sharpbits/overview.md: Created an overview page for common pitfalls and issues in RxInfer, along with guidelines for contributing to this section.
docs/src/manuals/sharpbits/rule-not-found.md: Added detailed documentation on handling RuleNotFoundError, including causes, common scenarios, and solutions.
docs/src/manuals/sharpbits/stack-overflow-inference.md: Provided guidance on preventing StackOverflowError during inference, with examples and performance considerations.
docs/src/manuals/sharpbits/usage-colon-equality.md: Explained the use of := for deterministic nodes and the reasoning behind not using =.

Enhanced error handling:

src/inference/inference.jl: Improved error messaging for StackOverflowError during inference, including suggestions for resolving the issue and links to relevant documentation. [1] [2]

codecov · 2024-12-18T10:46:40Z

Codecov Report

Attention: Patch coverage is 75.00000% with 1 line in your changes missing coverage. Please review.

Project coverage is 84.70%. Comparing base (74753ca) to head (8d82cba).
Report is 14 commits behind head on main.

Files with missing lines	Patch %	Lines
src/inference/inference.jl	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #391      +/-   ##
==========================================
+ Coverage   84.45%   84.70%   +0.24%     
==========================================
  Files          19       19              
  Lines        1525     1523       -2     
==========================================
+ Hits         1288     1290       +2     
+ Misses        237      233       -4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

abpolym · 2024-12-18T12:24:22Z

I'll check it out later today. I assume I can create the docs locally with make docs?

bvdmitri · 2024-12-18T12:55:52Z

yes make docs command should be enough

abpolym · 2024-12-18T14:52:04Z

make docs first threw warnings that examples at docs/src/examples do not exist, so I had to make them with make examples.

It continued by throwing an error:
Error: failed to run @example block in src/manuals/sharpbits/stack-overflow-inference.md:31-5.

make docs does still not work after make examples (for Julia 1.10).
I saw that CI does run with Julia 1.11 so I am testing make docs with 1.11.

Edit: 1.11.2 also yields an error:

Error: renderer for julia:cairo is unavailable 
ERROR: LoadError: MethodError: no method matching show(::IOContext{Base64.Base64EncodePipe}, ::MIME{Symbol("image/png")}, ::Nothing)
The function `show` exists, but no method is defined for this combination of argument types.

I have no idea what I have to do to fix those errors for either Julia version, so instead of rendering the markdown files, I am going through the markdown files individually in the branch.

bvdmitri · 2024-12-19T09:21:50Z

make docs first threw warnings that examples at docs/src/examples do not exist, so I had to make them with make examples.

yeah, its a warning, not an error, it will work without examples just fine, I also don't have them since they take a lot of time to compute

It continued by throwing an error: Error: failed to run @example block in src/manuals/sharpbits/stack-overflow-inference.md:31-5.

Well this is interesting, I don't have this error, perhaps there is a bug or smth

I have no idea what I have to do to fix those errors for either Julia version

Well this is jammer, I don't have these errors and CI seems to work just fine too, not sure what can be the reason... :(

src/inference/inference.jl

bvdmitri · 2024-12-23T09:50:44Z

Error: renderer for julia:cairo is unavailable

@abpolym Indeed https://discourse.julialang.org/t/issue-occurring-randomly-with-1-11/121233/4
also happens on CI now https://github.com/ReactiveBayes/RxInfer.jl/actions/runs/12463475091/job/34786844959

abpolym

Still need to be able to see the proper rendering, but the changes look very nice/informative so far.

abpolym · 2024-12-23T10:49:51Z

docs/src/manuals/sharpbits/rule-not-found.md

+3. The interface through which the message is being computed
+4. The inference method being used (Belief Propagation or Variational Message Passing)
+
+The last point is particularly important - some message update rules may exist for Variational Message Passing (VMP) but not for Belief Propagation (BP), or vice versa. This is because VMP and BP use different mathematical formulations for computing messages.


For the last sentence This is because VMP and BP use different mathematical formulations for computing messages, can we give the reader an explanation what "different mathematical formulations for computing messages" mean, s.t. (s)he can then hopefully immediately recognize the cause of the error?
Maybe we link to another part of our documentation that explains in more detail the difference BP vs VMP or equivalently exact bayesian inference vs variational inference?
We mention conjugacy (conjugate priors / conjugate pairs of distributions) in a few lines below without explanation, then again at the solution section with a link to wiki. Maybe we can just move all the detailed explanations into a separate document and tell the reader to read up on conjugate priors before creating models or when encountering this error?

abpolym · 2024-12-23T10:55:07Z

docs/src/manuals/sharpbits/rule-not-found.md

+- Avoids potential numerical instabilities from approximations
+- Throws an error when analytical solutions don't exist
+
+This means you may encounter `RuleNotFoundError` even in cases where approximate solutions could theoretically work. This is intentional - RxInfer will tell you explicitly when you need to consider alternative approaches (like those described in the Solutions section below) rather than silently falling back to potentially slower or less reliable approximations.


This means you may encounter RuleNotFoundError even in cases where approximate solutions could theoretically work.

A reader might ask if it is then possible to let RxInfer explicitly try approximate solutions and how to do so, i.e. how to trigger variational inference? To immediately quench that thirst for someone that is impatient, can we mention right after this sentence that a reader can trigger approximations by following "these instructions", where "these instructions" just links forward to the "use approximations" subsection?

abpolym · 2024-12-23T10:59:13Z

docs/src/manuals/sharpbits/rule-not-found.md

+
+To better understand where message passing rules are needed, let's look at a simple factor graph visualization:
+
+```mermaid


This is cool! I don't know how it will look like after (HTML) rendering as I am currently looking at the markdown version - which in my case is a bit broken (I use dark theme so most of it is not visible, the μx→f text does not render properly and the text itself is cut off).
I will have to wait for the cairo-related error to be fixed/resolved, until I can view this mermaid graph in its full glory.

abpolym · 2024-12-23T11:00:47Z

docs/src/manuals/sharpbits/rule-not-found.md

+
+### 1. Convert to conjugate pairs
+
+First, try to reformulate your model using conjugate prior-likelihood pairs. Conjugate pairs have analytical solutions for message passing and are well-supported in RxInfer. For example, instead of using a Normal likelihood with Beta prior on its precision, use a Normal-Gamma conjugate pair. See [Conjugate prior - Wikipedia](https://en.wikipedia.org/wiki/Conjugate_prior#Table_of_conjugate_distributions) for a comprehensive list of conjugate distributions.


You've been using code blocks for distributions like Normal, Beta everywhere but here 😄 .

abpolym · 2024-12-23T11:04:53Z

docs/src/manuals/sharpbits/stack-overflow-inference.md

+
+You can enable stack depth limiting by passing it through the `options` parameter to the `infer` function:
+
+```@example stack-overflow-inference


Is it possible to use julia code blocks?

I think if I just add "julia" right after the three dashes "`" but before the (at)example then it should use color highlighting?

Test:

using RxInfer @model function long_state_space_model(y) x[1] ~ Normal(mean = 0.0, var = 1.0) y[1] ~ Normal(mean = x[1], var = 1.0) for i in 2:length(y) x[i] ~ Normal(mean = x[i - 1], var = 1.0) y[i] ~ Normal(mean = x[i], var = 1.0) end end data = (y = rand(10000), ) using Test #hide @test_throws StackOverflowError infer(model = long_state_space_model(), data = data) #hide results = infer( model = long_state_space_model(), data = data, options = ( limit_stack_depth = 100, # note the comma ) )

it uses highlighted julia code blocks with @example stack-overflow-inference, see here, these are julia code blocks that are also being executed during the creation of the documentation page, just julia will only highlight but not execute

abpolym · 2024-12-23T11:06:33Z

docs/src/manuals/sharpbits/stack-overflow-inference.md

+
+For more details about inference options and execution, see:
+- [Static Inference](@ref manual-static-inference) documentation
+- The `options` parameter in the [`infer`](@ref) function documentation


I assume these references will render properly in HTML, in markdown it is broken 😢

yes because there are not from markdown, but from Documenter.jl

Co-authored-by: Fons van der Plas <[email protected]>

bvdmitri · 2024-12-23T13:10:55Z

Thanks @abpolym!

albertpod

Given the incorporation of suggested changes from others, LGTM

bvdmitri added 4 commits December 18, 2024 09:51

add stack overflow page

24e55b1

2prev

fad129a

add sharp bits and invite users to the discussions

997736e

invite users to the discussions

724ba13

bvdmitri requested review from wmkouw, fonsp, albertpod, wouterwln, bartvanerp and abpolym December 18, 2024 10:17

fix small inconsistency

685b5bb

bvdmitri added 2 commits December 18, 2024 13:00

fix build

b91e530

add mermaid explanation

f52fec6

Merge branch 'main' into sharp-bits

7a43f86

bvdmitri mentioned this pull request Dec 19, 2024

Issue in the dot product within a NormalMeanVariance distribution #390

Closed

fonsp reviewed Dec 20, 2024

View reviewed changes

src/inference/inference.jl Outdated Show resolved Hide resolved

abpolym reviewed Dec 23, 2024

View reviewed changes

bvdmitri added 3 commits December 23, 2024 14:02

feedback from Fons

fd8284d

Co-authored-by: Fons van der Plas <[email protected]>

more feedback

bec19bc

more feedback

45957fa

Merge branch 'main' into sharp-bits

8d82cba

albertpod approved these changes Dec 23, 2024

View reviewed changes

bvdmitri merged commit a6b3dfa into main Dec 23, 2024
6 of 7 checks passed

bvdmitri deleted the sharp-bits branch December 23, 2024 19:47

This was referenced Dec 23, 2024

Enhance error handling: implement user-friendly error messages for common issues #386

Closed

Intercept errors and point users to a discussion platform #385

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add sharp bits section and invite users to the discussions upon error #391

Add sharp bits section and invite users to the discussions upon error #391

bvdmitri commented Dec 18, 2024

codecov bot commented Dec 18, 2024 •

edited

Loading

abpolym commented Dec 18, 2024

bvdmitri commented Dec 18, 2024

abpolym commented Dec 18, 2024 •

edited

Loading

bvdmitri commented Dec 19, 2024 •

edited

Loading

bvdmitri commented Dec 23, 2024

abpolym left a comment

abpolym Dec 23, 2024

abpolym Dec 23, 2024

abpolym Dec 23, 2024

abpolym Dec 23, 2024

abpolym Dec 23, 2024

bvdmitri Dec 23, 2024

abpolym Dec 23, 2024

bvdmitri Dec 23, 2024

bvdmitri commented Dec 23, 2024

albertpod left a comment


		To better understand where message passing rules are needed, let's look at a simple factor graph visualization:

		```mermaid


		### 1. Convert to conjugate pairs

		First, try to reformulate your model using conjugate prior-likelihood pairs. Conjugate pairs have analytical solutions for message passing and are well-supported in RxInfer. For example, instead of using a Normal likelihood with Beta prior on its precision, use a Normal-Gamma conjugate pair. See [Conjugate prior - Wikipedia](https://en.wikipedia.org/wiki/Conjugate_prior#Table_of_conjugate_distributions) for a comprehensive list of conjugate distributions.


		You can enable stack depth limiting by passing it through the `options` parameter to the `infer` function:

		```@example stack-overflow-inference

Add sharp bits section and invite users to the discussions upon error #391

Add sharp bits section and invite users to the discussions upon error #391

Conversation

bvdmitri commented Dec 18, 2024

codecov bot commented Dec 18, 2024 • edited Loading

Codecov Report

abpolym commented Dec 18, 2024

bvdmitri commented Dec 18, 2024

abpolym commented Dec 18, 2024 • edited Loading

bvdmitri commented Dec 19, 2024 • edited Loading

bvdmitri commented Dec 23, 2024

abpolym left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bvdmitri commented Dec 23, 2024

albertpod left a comment

Choose a reason for hiding this comment

codecov bot commented Dec 18, 2024 •

edited

Loading

abpolym commented Dec 18, 2024 •

edited

Loading

bvdmitri commented Dec 19, 2024 •

edited

Loading