{"id":21334920,"url":"https://github.com/reactivebayes/rxinfer.jl","last_synced_at":"2025-04-05T07:02:19.741Z","repository":{"id":37202727,"uuid":"501995296","full_name":"ReactiveBayes/RxInfer.jl","owner":"ReactiveBayes","description":"Julia package for automated Bayesian inference on a factor graph with reactive message passing","archived":false,"fork":false,"pushed_at":"2024-04-12T16:57:48.000Z","size":255465,"stargazers_count":214,"open_issues_count":18,"forks_count":21,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-04-14T06:48:37.463Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ReactiveBayes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-06-10T10:12:10.000Z","updated_at":"2024-07-19T15:00:30.113Z","dependencies_parsed_at":"2024-01-15T09:48:55.304Z","dependency_job_id":"bd40815e-7783-4e88-acf5-22e0f6682f21","html_url":"https://github.com/ReactiveBayes/RxInfer.jl","commit_stats":{"total_commits":334,"total_committers":11,"mean_commits":"30.363636363636363","dds":"0.14071856287425155","last_synced_commit":"2276c082c4c44e1c6db25fb8fc193a4ea5289179"},"previous_names":["reactivebayes/rxinfer.jl","biaslab/rxinfer.jl"],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReactiveBayes%2FRxInfer.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReactiveBayes%2FRxInfer.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReactiveBayes%2FRxInfer.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReactiveBayes%2FRxInfer.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ReactiveBayes","download_url":"https://codeload.github.com/ReactiveBayes/RxInfer.jl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299829,"owners_count":20916190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-21T23:36:22.055Z","updated_at":"2025-04-05T07:02:19.713Z","avatar_url":"https://github.com/ReactiveBayes.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](docs/src/assets/biglogo-blacktheme.svg?raw=true\u0026sanitize=true)\n\n[![Official page](https://img.shields.io/badge/official%20page%20-RxInfer-blue)](https://rxinfer.com)\n[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://docs.rxinfer.com/stable/)\n[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://docs.rxinfer.com/dev/)\n[![Examples](https://img.shields.io/badge/examples-RxInfer-brightgreen)](https://examples.rxinfer.com/)\n[![Q\u0026A](https://img.shields.io/badge/Q\u0026A-RxInfer-orange)](https://github.com/reactivebayes/RxInfer.jl/discussions)\n[![Roadmap](https://img.shields.io/badge/roadmap-RxInfer-yellow)](#roadmap)\n[![Build Status](https://github.com/reactivebayes/RxInfer.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/reactivebayes/RxInfer.jl/actions/workflows/CI.yml?query=branch%3Amain)\n[![Coverage](https://codecov.io/gh/reactivebayes/RxInfer.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/reactivebayes/RxInfer.jl)\n[![Downloads](https://img.shields.io/badge/dynamic/json?url=http%3A%2F%2Fjuliapkgstats.com%2Fapi%2Fv1%2Fmonthly_downloads%2FRxInfer\u0026query=total_requests\u0026suffix=%2Fmonth\u0026label=Downloads)](https://juliapkgstats.com/pkg/RxInfer)\n[![DOI](https://img.shields.io/badge/Journal%20of%20Open%20Source%20Software-10.21105/joss.05161-critical)](https://doi.org/10.21105/joss.05161)\n[![Zenodo](https://img.shields.io/badge/Zenodo-10.5281/zenodo.7774921-important)](https://zenodo.org/badge/latestdoi/501995296)\n\n\n# Overview\n\n`RxInfer.jl` is a Julia package for automatic Bayesian inference on a factor graph with reactive message passing.\n\nGiven a probabilistic model, RxInfer allows for an efficient message-passing based Bayesian inference. It uses the model structure to generate an algorithm that consists of a sequence of local computations on a factor graph representation of the model.\n\n### Performance and scalability\n\nRxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running Bayesian inference with message passing. Below is a comparison between RxInfer.jl and Turing.jl on latent state estimation in a linear multi-variate Gaussian state-space model. [Turing.jl](https://github.com/TuringLang/Turing.jl) is a state-of-the-art Julia-based general-purpose probabilistic programming package and is capable of running inference in a broader class of models. Still, RxInfer.jl executes the inference task in [various models](https://examples.rxinfer.com) faster and more accurately. RxInfer.jl accomplishes this by taking advantage of any conjugate likelihood-prior pairings in the model, which have analytical posteriors that are known by RxInfer.jl. As a result, in models with conjugate pairings, RxInfer.jl often beats general-purpose probabilistic programming packages in terms of computational load, speed, memory and accuracy. Note, however, that RxInfer.jl also supports non-conjugate inference and is continually improving in order to support a larger class of models.\n\nTuring comparison             |  Scalability performance\n:-------------------------:|:-------------------------:\n![](benchmarks/plots/lgssm_comparison.svg?raw=true\u0026sanitize=true)  |  ![](benchmarks/plots/lgssm_scaling.svg?raw=true\u0026sanitize=true)\n\n\u003e [!NOTE]\n\u003e See many more examples in the [RxInferExamples.jl](https://examples.rxinfer.com/) repository.\n\n### Faster inference with better results\n\nRxInfer.jl not only beats generic-purpose Bayesian inference methods in conjugate models, executes faster, and scales better, but also provides more accurate results. Check out more examples [here](https://examples.rxinfer.com)!\n\nInference with RxInfer             |  Inference with HMC\n:-------------------------:|:-------------------------:\n![](benchmarks/plots/inference_rxinfer.svg?raw=true\u0026sanitize=true)  |  ![](benchmarks/plots/inference_turing.svg?raw=true\u0026sanitize=true)\n\nThe benchmark and accuracy experiment, which generated these plots, is available in the `benchmarks/` folder. Note, that the execution speed and accuracy \nof the HMC estimator heavily depends on the choice of hyperparameters. \nIn this example, RxInfer executes exact inference consistently and does not depend on any hyperparameters.\n\n### References\n\n- [RxInfer: A Julia package for reactive real-time Bayesian inference](https://doi.org/10.21105/joss.05161) - a reference paper for the `RxInfer.jl` framwork.\n- [Reactive Probabilistic Programming for Scalable Bayesian Inference](https://pure.tue.nl/ws/portalfiles/portal/313860204/20231219_Bagaev_hf.pdf) - a PhD dissertation outlining core ideas and principles behind `RxInfer` ([link2](https://research.tue.nl/nl/publications/reactive-probabilistic-programming-for-scalable-bayesian-inferenc), [link3](https://github.com/bvdmitri/phdthesis)).\n- [Variational Message Passing and Local Constraint Manipulation in Factor Graphs](https://doi.org/10.3390/e23070807) - describes theoretical aspects of the underlying Bayesian inference method.\n- [Reactive Message Passing for Scalable Bayesian Inference](https://doi.org/10.48550/arXiv.2112.13251) - describes implementation aspects of the Bayesian inference engine and performs benchmarks and accuracy comparison on various models.\n- [A Julia package for reactive variational Bayesian inference](https://doi.org/10.1016/j.simpa.2022.100299) - a reference paper for the `ReactiveMP.jl` package, the underlying inference engine.\n\n# Installation\n\nInstall RxInfer through the Julia package manager:\n\n```\n] add RxInfer\n```\n\nOptionally, use `] test RxInfer` to validate the installation by running the test suite.\n\n# Documentation\n\nFor more information about `RxInfer.jl` please refer to the [documentation](https://docs.rxinfer.com).\n\n# Getting Started\n\n\u003e [!NOTE]\n\u003e There are examples available to get you started in the [RxInferExamples.jl](https://examples.rxinfer.com/) repository.\n\n### Coin flip simulation\n\nHere we show a simple example of how to use RxInfer.jl for Bayesian inference problems. In this example we want to estimate a bias of a coin in a form of a probability distribution in a coin flip simulation.\n\nFirst let's setup our environment by importing all needed packages:\n```julia\nusing RxInfer, Random\n```\n\nWe start by creating some dataset. For simplicity in this example we will use static pre-generated dataset. Each sample can be thought of as the outcome of single flip which is either heads or tails (1 or 0). We will assume that our virtual coin is biased, and lands heads up on 75% of the trials (on average).\n\n```julia\nn = 500  # Number of coin flips\np = 0.75 # Bias of a coin\n\ndistribution = Bernoulli(p) \ndataset      = rand(distribution, n)\n```\n\n### Model specification\n\nIn a Bayesian setting, the next step is to specify our probabilistic model. This amounts to specifying the joint probability of the random variables of the system.\n\n#### Likelihood\nWe will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.\n\n```math\ny_i \\sim \\mathrm{Bernoulli}(\\theta)\n```\n\nwhere $y_i = 1$ represents \"heads\", $y_i = 0$ represents \"tails\". The underlying probability of the coin landing heads up for a single coin flip is $\\theta \\in [0,1]$.\n\n#### Prior\nWe will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.\n\n```math\n\\theta \\sim Beta(a, b)\n```\n\nwhere $a$ and $b$ are the hyperparameters that encode our prior beliefs about the possible values of $\\theta$. We will assign values to the hyperparameters in a later step.   \n\n#### Joint probability\nThe joint probability is given by the multiplication of the likelihood and the prior, i.e.\n\n```math\nP(y_{1:N}, \\theta) = P(\\theta) \\prod_{i=1}^N P(y_i | \\theta).\n```\n\nNow let's see how to specify this model using [GraphPPL's package](https://github.com/ReactiveBayes/GraphPPL.jl) syntax:\n```julia\n# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds a factor graph under the hood\n@model function coin_model(y, a, b) \n    # We endow θ parameter of our model with some prior\n    θ ~ Beta(a, b)\n    # We assume that outcome of each coin flip \n    # is governed by the Bernoulli distribution\n    for i in eachindex(y)\n        y[i] ~ Bernoulli(θ)\n    end  \nend\n```\n\nIn short, the `@model` macro converts a textual description of a probabilistic model into a corresponding [Factor Graph](https://en.wikipedia.org/wiki/Factor_graph) (FG). In the example above, the $\\theta \\sim \\mathrm{Beta}(a, b)$ expression creates latent variable $θ$ and assigns it as an output of $\\mathrm{Beta}$ node in the corresponding factor graph. The `~` operation can be understood as _\"is modelled by\"_. Next, we model each data point `y[i]` as $\\mathrm{Bernoulli}$ distribution with $\\theta$ as its parameter.\n\n\u003e [!TIP]\n\u003e Alternatively, we could use the broadcasting operation:\n```julia\n@model function coin_model(y, a, b) \n    θ  ~ Beta(a, b)\n    y .~ Bernoulli(θ) \nend\n```\n\nAs you can see, `RxInfer` in combination with `GraphPPL` offers a model specification syntax that resembles closely to the mathematical equations defined above. \n\n### Inference specification\n\nOnce we have defined our model, the next step is to use `RxInfer` API to infer quantities of interests. To do this we can use a generic `infer` function from `RxInfer.jl` that supports static datasets.\n\n```julia\nresult = infer(\n    model = coin_model(a = 2.0, b = 7.0),\n    data  = (y = dataset, )\n)\n```\n\n![Coin Flip](docs/src/assets/img/coin-flip.svg?raw=true\u0026sanitize=true \"Coin-Flip readme results\")\n\n# Roadmap\n\nOur high-level project roadmap outlines the key milestones and focus areas for the upcoming years:\n\n| Q1/Q2 2024          | Q3/Q4 2024                | 2025                | \n|---------------------|---------------------------|--------------------|\n| 🧩 **Nested models with [GraphPPL.jl](https://github.com/reactivebayes/GraphPPL.jl)** ✅    | 🌐 **Graph structure visualization** ✅ | 🧠🧠 **Automated Inference** |\n| 🔄 **Development of [ExponentialFamilyProjection.jl]()** ✅                | 🧠 **Semi-automated inference with [ExponentialFamilyProjection.jl](https://github.com/reactivebayes/ExponentialFamilyProjection.jl)** ✅| 🚀 **Stochastic Processes** |\n\nFor a more granular view of our progress and ongoing tasks, check out our [project board](https://github.com/orgs/reactivebayes/projects/2/views/4) or join our 4-weekly [public meetings](https://dynalist.io/d/F4aA-Z2c8X-M1iWTn9hY_ndN).\n\n\n## Ecosystem\n\nThe `RxInfer` framework consists of four *core* packages developed by [ReactiveBayes](https://github.com/reactivebayes/):\n\n- [`ReactiveMP.jl`](https://github.com/reactivebayes/ReactiveMP.jl) - the underlying message passing-based inference engine\n- [`GraphPPL.jl`](https://github.com/reactivebayes/GraphPPL.jl) - model and constraints specification package\n- [`ExponentialFamily.jl`](https://github.com/reactivebayes/ExponentialFamily.jl) - package for exponential family distributions\n- [`Rocket.jl`](https://github.com/reactivebayes/Rocket.jl) - reactive extensions package for Julia \n\n# Where to go next?\n\nThere are a set of [examples](https://examples.rxinfer.com/) available in the `RxInferExamples.jl` repository that demonstrate the more advanced features of the package. Alternatively, you can head to the [documentation](https://docs.rxinfer.com) that provides more detailed information of how to use `RxInfer` to specify more complex probabilistic models.\n\n\n# Join Our Community and Contribute to RxInfer\n\nRxInfer is a community-driven project and we welcome all contributions! To get started:\n- Check out our [contributing guide](https://docs.rxinfer.com/stable/contributing/guide)\n- Review the [contributing guidelines](https://docs.rxinfer.com/stable/contributing/guidelines)\n- Browse [beginner-friendly issues](https://github.com/ReactiveBayes/RxInfer.jl/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) to find something that interests you\n\n## Active Inference Institute Collaboration\n\nThe [Active Inference Institute](https://www.activeinference.org/) community members are enhancing RxInfer/GraphPPL's visualization capabilities. Their work includes:\n- Developing advanced model visualization features ✅ ([PR](https://github.com/ReactiveBayes/GraphPPL.jl/pull/251))\n- Creating summary and subgraph visualization modalities\n- Implementing various graph layout algorithms\n- Improving model inspection and understanding tools\n\nFor more details on ongoing work, see the [RxInfer development project board](https://coda.io/d/RxInfer-2024-Active-Inference-Institute_ddtS-XZ4BJb/Developing-RxInfer-jl_sufeCeIa#_lutfq_7F).\n\n## Learning Resources\n\nThe community maintains educational content and tutorials on [Learnable Loop](https://learnableloop.com/#category=RxInfer), covering topics such as:\n- Visualizing Forney Factor Graphs\n- Sales forecasting with time-varying autoregressive models\n- Hidden Markov models with control\n- Applications of Active Inference across different domains\n\n## JuliaCon 2023 presentation\n\nAdditionally, checkout our [video from JuliaCon 2023](https://www.youtube.com/watch?v=qXrvDVm_fnE) for a high-level overview of the package\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://www.youtube.com/watch?v=qXrvDVm_fnE\"\u003e\u003cimg style=\"width: 100%\" src=\"https://img.youtube.com/vi/qXrvDVm_fnE/0.jpg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Our presentation at the Julia User Group Munich meetup\n\nAlso check out the recorded presentation at the Julia User Group Munich meetup for a more detailed overview of the package\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://www.youtube.com/watch?v=KuluqEzFtm8\"\u003e\u003cimg style=\"width: 100%\" src=\"https://img.youtube.com/vi/KuluqEzFtm8/0.jpg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n# Telemetry\n\nRxInfer collects completely anonymous telemetry data regarding package usage. This information helps us understand how RxInfer is used and shapes our roadmap to prioritize features and improvements. The telemetry:\n- Does not collect any code, data, or environment information, only the fact of `using RxInfer` once per Julia session\n- Entirely anonymous\n- (Opt-out) Can be disabled for a single Julia session or permanently\n\nYou can learn more about it and how to opt-out by visiting our [documentation](https://docs.rxinfer.com).\n\n## Session Sharing\n\nRxInfer includes an optional session sharing feature that can help us provide better support and improve the package. When you encounter an issue, you can share your session data with us, which includes:\n- Model source code and metadata\n- Input data characteristics (no actual data)\n- Execution timing and success rates\n- Error information (if any)\n- Environment information (Julia version, OS, etc.)\n\nThis information is invaluable for debugging issues and improving RxInfer. Session sharing is:\n- Completely optional and disabled by default\n- Entirely anonymous\n- Only shared when you explicitly choose to do so\n- (Opt-in) Can be enabled to send reports automatically when an error occurs. When enabled, still entirely anonymous.\n\nIf you're opening a GitHub issue, we encourage you to share your session ID with us - it helps us understand your use case better and provide more accurate support. Learn more about session sharing and how to opt-in in our [documentation](https://docs.rxinfer.com).\n\n# License\n\n[MIT License](LICENSE) Copyright (c) 2021-2024 BIASlab, 2024-present ReactiveBayes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freactivebayes%2Frxinfer.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freactivebayes%2Frxinfer.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freactivebayes%2Frxinfer.jl/lists"}